13 tips to comment your code

1. Comment each level

Annotate each code block with a uniform method for each level, for example:

• Contains a brief description, author, and last modification date for each class.
• For each method, including its purpose, function, parameter, and return value

It is important to adopt standard annotations for team programming. Of course, using code protocols and tools (such as XML in C # And javadoc in Java) is acceptable and even more desirable.

2. Use paragraph comments

The code block is divided into multiple segments, each segment executes a simple task, and then adds comments before each segment to guide the reader about to happen.

// Check that all data records
// Are correct
Foreach (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

When multiple rows are followed by comments, we should arrange these comments to make them easier to understand.

Const max_items = 10; // maximum number of packets
Const mask = 0x1f; // mask bit TCP

Some developers use tabs to arrange comments, while others use spaces. The best way is to use spaces, because in various editors and ides, the tab key acts in a variety of ways.

4. Don't insult the reader's intelligence

Avoid explicit comments, such:

If (A = 5) // If a equals 5
Counter = 0; // set the counter to zero

This is a waste of time writing unnecessary comments and distracting readers, because these details are easily inferred from your code.

5. Be polite

Avoid rude comments, such as "notice the stupid user has entered a negative number," or "This fixes the side effect produced by the pathetically inept implementation of the initial developer ". Such comments are hard to get good results in their program code, and you don't even know who will read such comments in the future, your boss, customer, or poor stupid newbie.

6. Get to the point

Do not write comments that have nothing to do with what you want to convey. Avoid jokes, poems, and repeated remarks. In short, keep comments concise and straightforward.

7. Use a consistent style

Some people think that comments should be written so that non-programmers can understand them, while others think that it is only for programmers. In any case, as a successful code comment policy, it should be consistent and always oriented to the same readers. In my opinion, I even doubt whether many non-programmers will read the code. Therefore, comments should be oriented to programmers.

8. Use special tags for internal use

During team development, a set of consistent labels are used as the communication between programmers. For example, many teams use the "Todo:" label to indicate the code segment to be appended:

Int estimate (int x, int y)
{
// Todo: implement the calculations
Return 0;
}

Tag comments do not interpret code. They often seek attention or pass information. However, if you use this method, you must write the information you want to transmit.

9. Comment Code while writing it

When writing code, add comments, which are clear in your mind. If you do not add it until the end of the process, it will be worth the effort. "I have no time to comment", "I'm in a hurry" and "The project is delayed" are simple excuses to prevent writing documents in code. Some developers think that you should write comments before writing code as a way to plan the final solution. 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)

When commenting on the code, you should not only consider that other developers may maintain your code in the future, but also consider yourself.

The great Phil haack once said: "As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code ."

As a result, we ourselves will be the first beneficiaries of excellent (clumsy) comments.

11. Update comments when you update the code

If the comment is not updated with the code, the Comment cannot be correct. The code and comments must be modified synchronously. Otherwise, your comments will make the work of the developers who maintain your code very difficult. Pay special attention to the situation where the refactoring tool automatically updates your code without changing your comments, which will lead to the same result.

12. The Golden Role of comment: readable code

One of the basic skills of programmers: let your code speak for yourself. Although some people who do not like to write comments suspect that this is a mess made by programmers, the fact is self-evident Code does not need to be helpful in writing easier-to-understand code or even changing annotations. For example, the self-evident code shown in my fluid interfaces article may be like this:

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 not required, and doing so may be contrary to the 4th. To write code that is easier to read, you may need to consider using the appropriate naming method (Stringer's rules) to ensure correct reduction and use of the code style guide. The result of not following this prompt may be that the comment seems to have apologized to the bad code.

13. share these tips with your colleagues

Although we noted in article 10th how we immediately benefited from excellent comments, these terms were useful to all developers, especially team development. Therefore, share these comments with your colleagues to write easy-to-understand and easy-to-maintain code.

From: [translation] 13 tips to comment your code