Painless software maintenance-documents and code

ProgramThere are often two difficulties during maintenance:

1. Do not know this sectionCodeWhat functions are implemented (code -- function );
2. I don't know what the function-business needs to achieve ).

It is easy to solve the first problem. Everyone is engaged in technology. They can drag them into the code and take a few minutes to understand: it turns out that this code finds the number that has been in the stopped state for the past three months from the database, and then places the number in a data table called quit_user.

The second problem is hard, and it is often hard to see from the code. Therefore, a large number of documents are created during the project development process to help developers communicate with this problem, this knowledge is also known to those who will maintain this code in the future.

We can find the documents related to this code, which says: This code puts the number that has been suspended for three months into a table named quit_user. One month later, these numbers are screened by another piece of code, and the recently paid numbers are deleted. The remaining users will be able to use them again after half a year of suspension.

Sadly, it is difficult for maintenance personnel to see such intimate documents. They often see that this code queries data from the xxx table according to the rules of XXX, and then processes the result data in the quit_user table, over. You still don't know what he is doing.

In addition, synchronization of documents and code is also a challenge. Not only is it a document, but even a comment in the Code, who can ensure that he actually describes the running mode of the system? Time constraints and incorrect understanding may lead to different documents and actual situations. We assume that the people who write documents and write comments are serious and do not make mistakes. They must also ignore some details and they cannot write anything. The details they ignore may cause trouble for future maintenance.

Many projects have this problem: Business and function are out of touch. People familiar with the customer's business design a series of functional points, these functional points according to the initial design can complete the customer's business. Then these functions are created by developers. Developers do not know users' business, but they only have functions in their eyes. At the time of maintenance, the business changes and the function is re-designed. After some modifications, the program runs well according to the developer's ideas, but the user shook his head with strength: "No, no, this is not the case. What we want is this ......" What business has the program solved.

What can accurately describe the running process of a program? Only the Code itself. In addition, well-designed code can well describe business. For example, in the previous article, a piece of code put the number in quit_user, and another piece of code screened out some numbers from the code to perform the Internet return. Both functions belong to one point in business, so we should write these two sections of Code together and encapsulate them. This is high cohesion. In addition, the operations in the Code should have nothing to do with other functions, unless that function has business in common with these two functions, other code should not know what quit_user is-This is low coupling.

The code of a project is always started with a large-scale idea, and then is getting closer and closer to the details, involving more and more technologies. But at the end of the writing, the Code should return to the description of the business itself. The closer the code is to business, the more help it provides for maintenance.

I want to maintain the financial management procedures of a company. I want to know if the employee's salary has been included in their personal income tax. I found the account (Accounting). He should have a method to run the account once every month and send the salery to emplyee. I found the salery and saw that it already contains tax. I found that the account used a Stratagy (policy) when calculating the tax ). He calls a policy named stratagy1998, which calculates personal income tax at the base of 800 yuan. Now this base number has changed, so I modified this stratagy1998 or replaced it with a new stratagy2005. This completes a change. And I know that such changes cannot affect irrelevant business things.

The document will always only mean "we thought about it at a certain moment", so it is impractical to keep the document synchronized with the code at all times. To know how the current program runs, only the code can tell us. The document should work with the code to do things that cannot be done by the Code. It should not conflict with the code.

The document should describe what the Code cannot be clearly stated, for example, the user's work scenario, who proposed a certain requirement, large-scale program design, running sequence of important objects, and system installation manual. For example, in the figure below, he clearly shows the position of the "sales" behavior in the overall demand. It is effort-consuming to clearly describe such a thing using code. Of course, the code can also be clearly stated. For example, the State-action mode can be used, but it is not as clear as a figure.

XP and agile methods advocate "Writing as few documents as possible", which is based on the design concept: To describe business with code and test code as much as possible, to facilitate knowledge exchange and maintenance. Code is the most important communication language. The document is required when the code is unclear.