Ten annotation tips to improve code readability share _ Related tips

This article describes ten annotation techniques for improving the readability of your code. Share to everyone for your reference, specific as follows:

Many programmers write code often do not pay attention to the readability of the code, so that others spend more time reading the code. In fact, as long as the programmer in writing code, pay attention to the code annotation, and in a reasonable format for the code annotation, so that people can easily see the code, but also convenient for their own later view. Here's a 10-plus-note tip:

1. Layers of annotations

Annotate each code block and use a uniform annotation method and style at each level. For example:

For each class: including summary information, author information, and recently modified date;

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

In team work, it is particularly important to use standardized annotations. Of course, using annotation specifications and tools (such as Javadoc in Xml,java in C #) can be a better way to push the annotation work to completion.

2. Use segmented annotations

If you have multiple blocks of code, and each block of code completes a single task, add a comment to the reader explaining the functionality of the code before each code block. Examples are as follows:

Check This 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. Add comments after line of code

If you want to add a comment for each line of multiple lines of code, add the comment for that line after each line of code, which is easy to understand. For example:

Const MAX_ITEMS = 10; Maximum number of packets
const MASK = 0x1F;  Mask bit TCP

When separating code and annotations, some developers use the TAB key, while others use the SPACEBAR. However, because of the inconsistent performance of the TAB key between the editors and the IDE tools, the best approach is to use the SPACEBAR.

4. Don't insult readers ' wisdom

Avoid the obvious note: Writing these useless comments will waste your time and will distract the reader's understanding of the code's details.

if (a = = 5)   //If a equals 5
  counter = 0;//Set the counter to zero

5. Courtesy Point

Avoid rude comments, such as: "Note that stupid users will enter a negative number" or "just fix this problem out of the hands of the original incompetent developer". Such comments can reflect how poorly the author is, and you never know who is going to read the notes, perhaps: your boss, your client, or the incompetent developer you just insulted.

6. Main points of concern

Don't write too many notes that need to be transferred and not easy to understand. Avoid the annotation of ASCII art, funny, poetic, hyperverbosity. In short, keep annotations simple and straightforward.

7. Use a consistent annotation style

Some people believe that annotations should be written to the extent that they can be understood by non-programmers. Other people think that annotations can be understood by developers. In any case, successful strategies for commenting code has already provided and elaborated the annotation consistency and the target reader. Personally, I suspect most non-programmers will read the code, so the comments should be for other developers.

8. Use a unique label

In order to facilitate communication with other programmers when working in a team, you should annotate with a consistent set of tabs. For example, it would take additional work for many teams to represent the code snippet with a TODO tag.

int estimate (int x, int y)
{
  //todo:implement The calculations return
  0;
}

Note labels should not be used to interpret code, it simply causes attention or conveys information. If you use this technique, remember to track and confirm what this information represents.

9. Add comments when code

Add a comment when writing code, and it's clear and complete thinking in your head. If you add the same comment at the end of the code, it will cost you more than one time. "I don't have time to write notes", "I'm Busy" and "The project has been postponed" is an excuse for not wanting to write a note. Some developers feel that they should write comments before code to clarify the idea. 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. Annotate your code for yourself

When commenting on your code, consider not only the developers who will maintain your code in the future, but you may also want to look at it yourself. In the words of Phil Haack, "Once a line of code is displayed on the screen, you become the defender of the Code." As a result, we will be the first beneficiaries (the victims) for the notes we write well (poor).