Code annotation 13 tips

This article was published on the blog VariableNotFound of the author Jos é M. Aguilar. Later, TimmMartin translated it into English and published it on DevTopics. The following describes how to comment out the 13 tips of the Code, which will help you better understand and maintain the code in the future. 1. Commenteachlevel (comments of each level have a unified style) Comment each code

This article is published on the blog Variable Not Found of the author Jos é M. Aguilar, and then translated by Timm Martin into English and published on DevTopics. The following describes how to comment out the 13 tips of the Code, which will help you better understand and maintain the code in the future. 1. Comment each level (comments of each level have a unified style) Comment each code

This article is published on the blog Variable Not Found of the author Jos é M. Aguilar, and then translated by Timm Martin into English and published on DevTopics.

The following describes how to comment out the 13 tips of the Code, which will help you better understand and maintain the code in the future.

1. Comment each level (comments of each level have a unified style)

Annotate each code block, and use a unified annotation Method on each level of code block. For example:

For a class, it should contain a simple description, author, and the latest change date.
The method should contain the description, functions, parameters, and return values of the purpose.

It is very important for a team to use unified annotation rules. Of course, it is more recommended to use annotation conventions and tools (for example, C # XML or Java Javadoc), which will make comments easier.

2. Use paragraph comments (comments for paragraphs)

Divide the code block into several "paragraphs" that complete the independent function, and add comments before each "section" to explain "what is going to happen" to the reader ".

// Check that all data records

// Are correct

Foreach (Record record in records)

{

If (rec. checkStatus () = Status. OK)

{

...

}

}

// Now we begin to perform

// Transactions

Context ctx = new ApplicationContext ();

Ctx. BeginTransaction ();

...

3. Align comments in consecutive lines (Align comments)

For multi-line code with suffix-based comments, you can edit the comments to align each line of comments to the same column.

Const MAX_ITEMS = 10; // maximum number of packets

Const MASK = 0x1F; // mask bit TCP

Some developers use tabs to align comments, while others use spaces. However, because tabs are different in different editors or ides, it is best to use spaces.

4. Don't insult the reader's intelligence (do not insult the reader's IQ)

Do not write useless comments, such:

If (a = 5) // if a equals 5

Counter = 0; // set the counter to zero

Writing such useless comments will not only waste your time, but will also be easily distracted by your comments when you are reading such easy-to-understand code.

5. Be polite (Be polite)

Do not write impolite comments, for example, "note that stupid Users enter a negative number", or "correct the side effects caused by the poor and stupid coding of the original developer ". Such comments offend the author, and you don't know who will read the comments in the future-your boss, customer, or the poor and stupid developer you offend in the comments.

6. Get to the point (concise)

Do not write too much in comments, and do not write jokes, poems, or lengthy words. In short, annotations must be simple and straightforward.

7. Use a consistent style (consistent style)

Some people think that comments should be understandable to non-programmers, but some people think that comments only guide programmers. In any case, as stated in Successful Strategies for Commenting Code, what really matters is that annotations are always oriented to the same reader. At this point, they should be consistent. I personally think that I suspect that non-programmers will read the code, so I should locate the object of reading comments as a developer.

Int Estimate (int x, int y)

{

// TODO: implement the calculations

Return 0;

}

9. Comment code while writing it (complete comments when writing code)

Add comments when writing code, because your thinking is the clearest at this time. If you leave the annotation task to the end, you have experienced two encodings. "I don't have time to comment" "I'm too busy" "project delay" is often the reason for not writing comments. Therefore, Programmers think that the most ideal solution is to 'write comments before writing Code '. For example:

Public void ProcessOrder ()

{

// Make sure the products are available

// Check that the customer is valid

// Send the order to the store

// Generate bill

}

10. Write comments as if they were for you (in fact, they are) Think of the readers of the Code as yourself (this is often the case in reality)

When commenting on the code, you should not only consider the person who may maintain your code in the future, but also consider that you may read the comments. The great Phil Haack said: "Every time a line of code is knocked on the screen, you have to review the code from the maintenance perspective. "" As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code. "(the famous words do not dare not include the original sentence)

As a result, we are often the beneficiaries of our good comments, or the victims of bad comments.

11. Update comments when you update the code (remember to Update the comments when updating the code)

If the comment cannot be updated with the code update, it is meaningless to make the comment more accurate. The code and comments must be synchronized. Otherwise, these comments will be a torment for programmers who maintain your code. When using the refactoring tool to automatically update code, pay special attention to the fact that they will automatically update the code without changing the comments. These comments will naturally expire.

12. The golden rule of comments: readable code (readable code is The best comment)

For many programmers, one of the basic principles is to let the code speak on its own. Some may doubt that this is an excuse for programmers who do not like to write comments. However, this is indeed an indisputable fact. Self-explanatory code is of great benefit to coding, not only the code is easy to understand or even make comments unnecessary. For example, my article Fluid Interfaces shows what self-explanatory code is:

Calculator calc = new Calculator ();

Calc. Set (0 );

Calc. Add (10 );

Calc. Multiply (2 );

Calc. Subtract (4 );

Console. WriteLine ("Result: {0}", calc. Get ());

In this example, annotations are unnecessary and violate tip #4. To make the code more readable, you should consider using appropriate names (as described in the classic Ottinger's Rules ), ensure correct indentation and code style bars (Code style bars are similar to # region # endregion, right ?). If this is not done well, your comments seem to be apologizing for obscure code.

13. Share these tips with your colleagues (share these tips with your colleagues)

Although tip #10 has said that good comments will be their own benefits, these tips will benefit all developers, especially in a team environment. Therefore, I am very generous to share these annotation skills with my colleagues, so that we can write easy-to-understand and well-maintained code.