table of Contents
Internal code documentation plays a vital role in software design. Note For help developers understand the system and work effectively is essential, but the effect is far more than that comment. Documents in the abstract also play an important role; no comment, we can not hide the complexity. Finally, the process of writing a comment if handled properly, will actually improve the design of the system. Conversely, if there is no good documentation, good software design will lose a lot of value.
Unfortunately, this view is not universally recognized. A considerable part of the product code is not substantially contain comments. Many developers believe that comment is a waste of time; others see the value of a comment, but somehow was never written. Fortunately, many of the development team recognized the value of the document, and feel the prevalence of these teams is gradually increasing. However, even encouraging documentation team, comments are also often seen as drudgery of work, many developers do not know how to write a comment, the generated documents are usually mediocre. Inadequate documentation of software development will cause huge and unnecessary drag.
In this chapter, I will discuss the excuse used by developers to avoid writing comments, and the comments really important. Chapter 13 describes how to write good comments, the next few chapters discuss relevant issues, such as selecting variable names and how to use the document to improve the design of the system. I hope these chapters make you believe in three things: good comments can make the overall quality of the software are very different; write good comments is not difficult; and (this may be hard to believe) is very interesting to write notes.
When developers do not write notes, they usually use one or more of the following reasons to explain their actions:
- Good code is self-explanatory.
- I do not have time to write comments.
- Comments out of date, misleading.
- I have seen comments are worthless, why?
In the following sections, I will explain in turn these excuses.
12.1 Good code is pretty self-explanatory
Some people believe that if the code is well written, you obviously do not need comments. This myth is a delicious, wholesome rumors like ice cream: do we really want to believe it. Unfortunately, it is not. Of course, when writing code can do something to reduce the need for annotation, such as select the appropriate variable name (see Chapter 14). Nevertheless, there are still a lot of design information can not be represented in code. For example, only officially designated signature type of a small part of the interface, as is a method in code. Informal aspect interface, for example, the meaning or results of high-level description of each method, only be described in the comment. There are many other examples in the code can not be described, such as the basic principles of a particular design decisions or conditional call a particular method.
Some developers believe that if other people want to know a way to do what they should read only the code for the method: This is more accurate than any comment. Readers can deduce abstract interface methods by reading the code, but it will be time consuming and painful. In addition, if you write code method to achieve the desired user to read, then you will try each of the methods as short as possible in order to read. If the method to do anything important, you will break it down into several smaller methods. This will lead to a lot of shallow approach. Moreover, it does not really make the code easier to read: In order to understand the behavior of the top-level method, the reader might need to understand the behavior of nesting methods. For large systems, user behavior to learn by reading the code is impractical.
In addition, comments are abstract basis . Recall from Chapter 4, abstract goal is to hide the complexity: Abstract is a simplified view of an entity, it retains the basic information, but ignored the details can be safely ignored. If the user must read the code to the method of using it, then there is no abstraction: all the complexity of the method are exposed. If there is no comment, only the abstract is its method of declaration, which specifies the name and type name, parameters and results of the method. Declared missing much of the basic information and can not provide a useful abstraction. For example, a method of extracting a substring may have two parameters, start, and End, represents the range of characters to be extracted. Can not only determine whether the declaration extracted substring contains characters end indicated, or if start> end what happens. Notes allows us to capture additional information about the caller needs, so while hiding implementation details to complete a simplified view. Equally important is that the comment is written in English and other human language; it makes them as good as the code exactly, but it provides additional capabilities, so we can create a simple, intuitive description. If you want to use abstraction to hide complexity, comments are essential.
12.2 I do not have time to write a comment
People tend to lower priority than other development tasks comment. If you want to add new features and records to choose between the existing properties, then select the new features seem to be logical. However, software projects are almost always under time pressure, and there are always some things that seem more important than the written comments. So, if you are allowed to cancel the priority document, the final document will not.
The opposite argument is an excuse for investment mentality discussed on page 15. If you want a clean software architecture, which will allow you to be productive in the long run, you have to spend some extra time in advance to create this structure. It has a huge impact maintainability of the software would be good comments, so energy spent annotation will soon be rewarded. In addition, written comments do not need to spend a lot of time. Ask yourself how much you spent development time to type (with respect to design, build, test, etc.), assuming you do not have any comment; I suspect the answer is more than 10%. Now suppose you enter a comment as much time with the time code input; this should be a safe upper limit. Based on these assumptions, write good comments will not increase by more than 10% of the development time. Benefits of having a good document will soon offset this cost.
In addition, many of the most important comments are related to the abstract, such as top-level document classes and methods. Chapter 15 discusses these comments should be written as part of the design process, while documenting the behavior of the overall design can be an important design tool as improvements. These comments are immediate.
12.3 comments are outdated and misleading
Comments do sometimes out of date, but in practice is not necessarily a major problem. Keeping documentation update does not require a massive effort. Only in the case of a larger code changes, only the need for greater changes to the document, and the document code changes than the change takes more time. Chapter 16 discusses how to organize documents, to the extent possible to easily update the document after the code is modified (key idea is to avoid duplication of documents, and documents with the corresponding code consistent). Code review to detect and repair the old notes provide a good mechanism.
12.4 I have seen all comments are worthless
In these four excuse, this may be the most valuable one. Each software developers are seen not provide any useful information, comments, and most of the existing document, at best, in general. Fortunately, this problem can be solved; the preparation of reliable documentation is not difficult, as long as you know how to do it. The next chapter will be on how to write good documentation and maintenance of a framework over time.
Benefits 12.5 Good comment
Now that I have discussed (hope has been debunked) argument against writing comments, let us consider the benefits can be obtained from the good comments. The general idea behind the comments is to capture information but not in the minds of the designers represented in the code. This information is very wide range, from low-level details (such as the drive for a particular hardware quirks of complex code), to high-level concepts (such as the basic principles of the class). When other developers to make changes later, the notes will allow them to work faster and more accurately. No documentation, future developers will have to deduce or guess the original developer of knowledge; this will take additional time, and if the new developer misunderstood the intent of the original designer, there will be a risk of the bug. Even the original designers made changes, the comment is valuable: If you use the code from your last more than a few weeks, you will forget many details of the original design.
The second chapter describes three ways manifested in the complexity of software systems:
- Enlarge change: a seemingly simple change you need to modify the code in many places.
- Cognitive load: In order to make a change, the developer must accumulate large amounts of information.
- Unknown Unknown: What is not clear need to modify the code, or to make these modifications which information must be considered.
Good documentation can help solve the last two questions. By providing the information they need to change the developer, and developers can easily ignore irrelevant information, documents may reduce the cognitive load. Without adequate documentation, developers may have to read a lot of code to reconstruct the idea of the designer. Documents can also be reduced by the structure of unknown unknowns clarify the system, so that you can understand what information and code related to any given change.
The second chapter points out the main reason is the complexity and ambiguity of dependence. Good documentation can clarify dependencies and fill in the blanks to eliminate ambiguity.
The next few chapters will show you how to write good documentation. They will also discuss how to write a document integrated into the design process, thereby improving design software.