Software design philosophy: Chapter XV the first to write a comment

Many developers working document will be prepared to defer to the end of the development process, that is, coding and unit testing is completed. This is one of the most reliable method to produce low-quality documents. The best time to start writing comments is in the process, that is, when writing code. First, the document written comments become part of the design process. This not only produces better documentation, but also produced a better design, and the process of writing the document more enjoyable.

15.1 Delay comments was a bad comment

I met almost all developers have delayed the time to write comments. When asked why not write a document earlier, they said code is still changing. They say, if they have long written document, then when the code changes, they must rewrite the document; better to wait until the code is stable. However, I suspect there is another reason that they regard documents as coolie work; therefore, they delay as much as possible.

Unfortunately, this approach has several negative consequences. First, the delay usually means that the document does not need to write the document. Once you start delay, it is easy to further delay a little; after all, a few weeks, the code will be more stable. Wait until the code settled down, there are already a lot, which means that the task of writing documentation has become very difficult, not even attractive. Never the right time to stop a few days, all the comments are missing to make up, and it is easy to think of the project is the best thing to move forward, bug fixes or new features to write next. This will create more undocumented code.

Even if you have the self-discipline to go back to write notes (do not deceive yourself: you may not), comments will not be good. At this point of the process, you have left in spirit. In your mind, this code has been completed; you are eager to start the next project. You know that's the right thing to write comments, but it's no fun. You just want to ride out the storm as soon as possible. Therefore, you can quickly browse through code, add enough comments to make it look satisfactory. So far, you have no design code for some time, so that you become blurred memories of the design process. You look at the code at the time of writing notes, annotations and therefore repeated code. Even if you are trying to reconstruct the code design is not obvious, there will be things that you do not remember. Therefore, these comments ignore some of the most important things they should be described.

15.2 the first to write a comment

I used a different method to write a comment, the comment I wrote at the beginning:

1. For a new class, I would first like to write interfaces comment.
2. Next, I write notes and signatures interfaces as the most important public, but the method body is empty.
3. I did some iteration of these comments, the basic structure of feeling until the correct date.
4. At this point, I wrote a statement and notes for the class of the most important class instance variables.
5. Finally, I fill in the body of the method, implementation comments added as needed.
6. In the preparation method body, I usually find that you need additional methods and instance variables. For each new method, I have a comment before the method body write interface; for instance variables, I fill out the comment while writing variable declarations.

After the code is complete, the comment also completed. Never comments no backlog of unwritten.

First annotation method has three advantages:

• First, it produces a better note. If you write down comments in the design category, then the key design issues will emerge in your mind, so it is easy to record.
• The best method to prepare before the main body of each interface notes, so you can focus on abstract and interface methods, without being distracted achieved.
• In the coding and testing process, you will notice and fix the problem in comments. Therefore, comments continuous improvement in the process of development.

15.3 Notes is a design tool

Write a comment at the start of the second advantage (and most important a benefit) is to improve the system design. Notes provides the only way to fully capture the abstract, abstraction is a good basis for good system design. If you write an abstract description of the comment at the beginning, you can check and tune them before writing implementation code. To write good comments, you must identify the nature of a variable or a piece of code: What is the most important aspect of this thing? Early in the design process to do this is very important, otherwise you just crack the code.

Notes is like the canary in the coal mine complex. If a method or variable takes a long comment, this is a warning that you do not have a good abstract. Remember, in Chapter 4, the class should be in-depth: The best class has a very simple interface, but realized the powerful. Best way to determine the complexity of the interface is described in accordance with its annotations. Notes If the interface method provides all the information needed to use this method, very simple and very short, this indicates that the method has a simple interface. Conversely, if there is no long and complicated annotations can not completely describe a method, then this method will have a complex interface. You can annotate and implement the interface methods are compared in order to understand the depth of this approach: if all the main features of the interface implementation comments must be described, the method is superficial. The same idea also applies to variables: If you take a long comment to completely describe a variable, this is a dangerous sign that you may not select the correct variable decomposition. In general, write comments behavior allows you to evaluate your design decisions as early as possible, so you can find and fix the problem.

Danger signals: indescribable

Notes describe the method or variable should be simple and complete. If you find it difficult to write such comments, it shows the design of things you have described may be a problem.

Of course, the comment can only be a good indication of the complexity in a complete and clear conditions. If you write an interface method comment was not all the information needed to provide the method call, or a comment is very obscure and difficult to understand, then the comment will not be a good measure of the depth of the method.

15.4 The early comments very interesting

Written comments as soon as the third and final benefit is that it allows annotation writing more interesting. For me, the most interesting part of the program is one of the early design phase of a new class, at this stage, I would like to enrich the abstract and structure. Most of my comments are written at this stage, these comments is how I record my design and test the quality of decision-making. I'm looking design that can express a full and clear with minimal language. The more simple comment, I felt better my design, so finding a simple comment is my pride. If you are strategically programmed your main goal is a great design, rather than just writing code to work, then write comments should be interesting, because this is the way you identify the best design.

15.5 earlier comments costly it?

Now, let's revisit the reasons for delays comments that it avoids the costs with the development of codes and reprocessing comments. A simple rough calculation would indicate that it did not have much savings. First, estimate your development time with the input code and comments it takes, including modifying code and comments of time; this is unlikely to exceed 10% of the total development time. Even if half of the total lines of code are your comments, written comments will not take up 5% of your entire development time. The comments until the last save only a small part of it, not a lot.

First written comments to mean that before you start writing code abstract will be more stable. This may save time during encoding. Conversely, if you write the code first, as you might abstract code developed, this method than the first comments require more code revisions. When you take into account all these factors, the first written comments may be faster.

15.6 Conclusion

If you have not tried to write a comment, try it. Adhere to the habit so far. Then consider how it affects your quality of comments, and enjoy the overall design quality and software development. After some time you try, let me know if your experience matches with me, and why or why not.