table of Contents
Chapter 1 describes how software development is iterative and incremental. Development of large software systems through a series of evolutionary stages, each stage adds new functionality and modify existing modules. This design means that the system is evolving. It can not be conceived at the outset of a properly designed system; a mature system design depends more on changes in the system development process, rather than the original concept. First few chapters describe how extrusion complexity in the initial design and implementation process; This chapter discusses how to prevent complexity with the development of the system increases.
16.1 maintain strategic
Chapter 3 describes the difference between tactical and strategic programming Programming: Programming in tactics, the main goal is to get something working quickly, even if this results in additional complexity; in strategic planning, the most important goal is to produce a great the design of the system. Tactical approach quickly lead to confusion design system. If you want an easy to maintain and enhance the system, then the "work" is not a high enough standard; you have to give priority to the design and strategically thinking. This idea also applies when modifying existing code.
Unfortunately, when developers go deep into existing code to make changes such as bug fixes or new features like, they usually do not think strategically. A typical attitude is "the smallest change what I can do to satisfy my needs? " "Sometimes developers do it because they do not like to modify the code; they fear will bring greater changes to introduce greater new bug risks. However, this has led to tactical planning. each of these minimal changes were introduced in some special cases, dependencies or other forms of complexity. As a result, system design becomes worse, problems every step in the evolution of the system accumulate.
If you want to maintain a clean system design, you must take strategic approach when modifying existing code. Ideally, when you complete each change, the system will have if you design in mind from the outset has a structure. To achieve this goal, you must resist the temptation of quick fixes. Instead, consider whether the current system is still the best design, change as needed. If not, the reconstruction of the system to get the best design. The system design can be improved with every modification by this method.
An example of this is the mindset of the investment described on page 15: If you invest a little extra time to reconstruct and improve system design, you will get a more compact system. This will speed up development, and you will recover your investment in the reconstruction effort. Even if your particular changes do not require reconstruction, you should also look to fix design flaws in the code. Whenever any code changes, we must try to improve the system design, at least to improve one o'clock in the process. If you do not make the design better, you might make it worse.
As we discussed in Chapter 3, the real investment mentality sometimes conflict with commercial software development. If the "right way" to reconstruct the system needs three months, while bad repair quickly and requires only two hours, you may have to take quick and bad way, especially in your working hours urgent case. Or, if the reconstruction of the system will result in incompatible, thus affecting the team and many other people, then reconstruction may not be practical.
However, you should resist these compromises as possible. Ask yourself: "Considering my current restrictions, this is the best I can do to create a clean system design?" Maybe there is a way, as simple as the reconstruction of three months, but can be within a few days to complete? Or, if you are unable to bear the cost of large-scale reconstruction, let your boss to give you the allotted time, so you do reconstruction after the current deadline. Each organization should develop a small part of its plan to all of the work for clean-up and reconstruction, the work is worth it in the long run.
16.2 Maintenance Notes: putting comments in the vicinity of the code
When you change an existing code, it may make some existing annotation failure. When modifying code is easy to forget to update the notes, which will result in the comment no longer be accurate. Inaccurate comments make readers feel frustrated if too many comments, readers will begin to doubt all comments. Fortunately, with a little rules and guidelines that can be updated without comment in a massive effort. The following sections of this section and made a number of specific techniques.
The best way to ensure that the comment is updated to place them in the vicinity of the code they describe, so developers can see them when you change the code. Comment farther away from the relevant code, the less correct update its possibilities. For example, the best position of the interface method is annotated code file, next to the method body. Any changes to the method will involve this code, so developers may see the interface comments and update them if necessary.
For such as C and having a c ++ language-independent code and header files, an alternative method is to interface aside .h file annotation method declaration. However, this is a long way from the code; developers when modifying the method body will not see these notes, and requires extra work to open the file and find the interface of different annotations to update them. Some people may think that comments should be placed in the interface header file, so that users can learn how to use the abstract, without having to look at the code file. However, the user does not need to read the code or header file; they should obtain information from the compilation tools such as Doxygen or Javadoc documentation. In addition, many ide will be displayed to the user to extract a document, such as document display method when typing method name. For such tools, documentation should be placed on developers to write code the most convenient place.
In the preparation of implementation comments, not all comments will be placed on top of the overall process method . They expand, each annotation pushed down to the narrowest range including all of the code to which it refers. For example, if a method has three main stages, do not write a note at the top of all the stages of the method described in detail. Instead, for each stage of the preparation of a single comment, and the comment is placed on the stage of the first line of code. On the other hand, a method of achieving topped with a comment describing the overall strategy is also helpful, like this:
// We proceed in three phases:
// Phase 1: Find feasible candidates
// Phase 2: Assign each candidate a score
// Phase 3: Choose the best, and remove it16.3 annotation belongs to the code, rather than commit log
When you modify the code, a common mistake is to put more information about the changes in the commit message source code repository, rather than recording it in the code. Although it is possible to browse the store by scanning the commit message logs in the future, but the information needs of these developers are less likely to think you want to scan the repository log. Even if they do scan log to find the correct log messages will be very cumbersome.
When writing a commit message, ask yourself whether the future developers need to use the information. If so, record the information in the code. Commit message is an example, which describes the delicate issue of a cause code changes. If there is no record of this code, so developers may occur later and undo the changes, but do not realize they re-created an error. If you also want to include a copy of the submission of this information in the message, that's great, but the most important thing is to get it in your code. This shows that the document on the local developers are most likely to see the principle ; commit log seldom in that place.
16.4 Reserved Note: to avoid duplication
Comment date of the second technique is to avoid duplication. If the document is a duplicate, the developer is difficult to find and update all copies. Instead, try to record only once every design decision. If there are multiple places affected by a particular decision-making code, then do not duplicate documents in each place. Instead, find the most obvious place to put the document. For example, suppose you have a complex behavior associated with the variable, it will affect the variables used several different locations. You can record the behavior in the comment next to the variable declaration. If developers have difficulty understanding the code using this variable, this is a very natural place.
If there is no "obvious" place to put a specific document, developers can find it, then create a designNotes file, as described in Section 13.7. Or, choose the best place to put the document in there. Also, add a reference center position elsewhere brief comment: "xyz view comments in order to understand the following explanation of the code." If you refer to as the main comment is moved or deleted become obsolete, this inconsistency will be self the metaphor, because developers will not find the comment in designated areas; they can use revision control history to find the comments what happened, and then update the references. On the contrary, if the document is duplicated, and some copies have not been updated, then the developer will not know they are using stale information.
If the information is already recorded somewhere outside the program, do not duplicate records within the program; just reference an external document. For example, if you write a class that implements the HTTP protocol, you do not need the HTTP protocol is described in the code. Internet has many sources on this document; just add a brief comment in your code, and as a source of which add a URL. Another example is already recorded in the user manual features. Suppose you are writing a program to achieve the set command, which is responsible for implementing a method for each command. If these commands are described in the user manual, you do not need to repeat the information in the code. Instead, in the interface comprising the short description of each command annotation method:
// Implements the Foo command; see the user manual for details.
Important is that the reader can easily find all the documents needed to understand your code, but that does not mean you have to write all the documents.
Do not re-record a module design decisions in another module . For example, not until a method is called with comments to explain what happened in the method is called in. If readers want to know, they should look at the interface annotation methods. Good development tools are often automatically provide this information, for example, if you select the name of a method or hover over it, it will display interface annotation of the method. Try to make it easy for developers to find the right document, but do not duplicate documents.
16.5 Maintenance Note: Check the difference
Make sure the document kept up to date is a good idea, before changes are committed to revision control system take a few minutes to scan to submit all changes to ensure that each change are properly reflected in the document. These scans will detect pre-commit several other issues, leaving the field wishful debugging code in the system fails to repair or TODO items.
16.6 higher level of annotation easier to maintain
On the maintenance of document A final thought: if the comment is more advanced than the code, more abstract, so they are easier to maintain. These comments do not reflect the details of the code, so they are not affected by minor changes to the code; only change will affect the overall behavior of these comments. Of course, as discussed in Chapter 13, some comments do need detailed and accurate. In general, however, the most useful comments (they do not simply repeat the code) is the easiest to maintain.