10 comments to improve code readability

Address: http://blog.jobbole.com/586/

ManyProgramThe employee is writingCodeOften do not pay attention to the readability of the Code, allowing others to spend more time reading the code. In fact, as long as programmers add comments to the Code while writing the code, and add comments to the Code in a reasonable format, it is convenient for others to view the Code and to view it later. The following are 10 tips for adding annotations:

1. layer-by-layer comment

Add comments to each code block and use a unified method and style for each layer. For example:

For each category: including abstract information, author information, and last modification date;

For each method: including purpose, function, parameter, and return value.

It is particularly important to adopt standardized annotations in team work. Of course, the use of annotation specifications and tools (such as XML in C # And javadoc in Java) can better promote the completion of annotation work.

2. Use segmented comments

If there are multiple code blocks, and each code block completes a single task, add a comment before each code block to explain the functions of this code to the reader. Example:

3. Add comments after the code line

If you need to add comments to each line of multi-line code, add the comments of this line after each line of code, which is easy to understand. For example:

When code and comments are separated, some developers use the tab key, while others use the space key. However, because the tab key is inconsistent between the editors and IDE tools, it is best to use the space key.

4. Do not insult your wisdom.

Avoid the following obvious comments: writing these useless comments will waste your time and will shift your understanding of the Code details.

5. Courtesy

Avoid rude comments, such as: "NOTE that stupid Users enter a negative number" or "the problem just fixed is due to initial incompetence of developers ". Such a comment can reflect how poor the author is, and you never know who will read the comment. It may be: your boss, customer, or the incompetent developer you have insulted just now.

6. Important Points

Do not write too many comments that need to be converted and hard to understand. Avoid ASCII art, funny, poetic, and hyperverbosity comments. In short, keep comments simple and direct.

7. Use consistent annotation styles

Some people firmly believe that comments should be written to a level that can be understood by non-programmers. Others think that comments can only be understood by developers. In any case, successful strategies for commenting code has defined and elaborated on the annotation consistency and target readers. Personally, I suspect that most non-programmers will read the code, so comments should be for other developers.

8. Use a unique tag

When working in a team, a consistent tag set should be used for comments to facilitate communication with other programmers. For example, in many teams, the todo label is used to indicate that the code segment requires additional work.

Note labels should not be used to interpret code. They only attract attention or pass information. If you use this technique, remember to track and confirm what the information represents.

9. Add comments when writing code

When writing code, add comments. In this case, you have a clear and complete idea in your mind. If you add the same comment at the end of the code, it will take twice as much time. "I don't have time to write comments", "I'm busy", and "The project has been extended" are all excuses for not wanting to write comments. Some developers think that the write comments before code should be used to clarify the clues. For example:

10. annotate the code for yourself

When commenting on the code, consider not only the developer who maintains your code in the future, but you may also want. In the words of Master Phil haack, "Once a line of code is displayed on the screen, you become the maintainer of this Code ". Therefore, we will be the first beneficiary (victim) of our well-written comments ).