13 Tips for Writing program notes

13 Tips for Writing program notes

1. Comment each level (comments in each category have a uniform style)

Comment on each block of code, and use a uniform annotation method on each level of code block. For example:

• For a class, you should include a simple description, the author, and the date of the most recent change
• For a method, the description, function, parameter, and return value of the purpose should be included

It is very important for a team to use uniform annotation rules. Of course, it is more recommended to use the conventions and tools for annotations (for example, C # XML or Java Javadoc), which can be more easily commented.

2. Use paragraph comments (comment on paragraph)

Break the code block into "paragraphs" that do separate functions and add comments before each paragraph to explain "What's going to happen" to the reader.

Check that all data records

is 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 comment lines)

For multiple lines of code that have suffix comments, layout the comment code so that the lines of comments are aligned to the same column.

Const MAX_ITEMS = 10; Maximum number of packets

Const MASK = 0x1F; Mask bit TCP

Some developers use tab to align comments, while others use spaces. However, because tab is different in the editor or IDE, it is best to use spaces.

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

Do not write useless comments, for example:

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

Counter = 0; Set the counter to zero

Writing this useless comment is not only a waste of your time, but it's easy for readers to be distracted by your comments when reading this easily understandable code, wasting time.

5. Be polite (to be polite)

Do not write impolite comment codes, such as "Note that the foolish user has entered a negative number", or "fix the side effects caused by the poor and foolish coding of the original developer." Such comments offend the author, and you do not know who will read the note in the future-your boss, your client, or the poor and foolish developer you have offended in the comments.

6. Get to the point (concise)

Don't write too much in the notes, don't write jokes, poems, or lengthy words. In summary, annotations need to be straightforward.

7. Use a consistent style (consistent style)

Some people think that annotations should be readable by non-programmers, but some people think that annotations are just a guide to programmers. In any case, as the successful strategies for commenting code says, what really matters is that annotations are always oriented towards the same reader, which should be consistent. Personally, I suspect that there will be non-program personnel reading the code, so the object reading the annotation should be positioned as a developer.

8. Use special tags for internal uses (special labels are used internally)

When working with code in a team, a series of unified ' tag annotations ' should be used to communicate between programmers. For example, many teams use "TODO" to represent a piece of code that needs extra work.

int Estimate (int x, int y)

{

Todo:implement the calculations

return 0;

}

' tag annotations ' do not explain the code, but rather cause ideas or convey information. However, when using this method, it is important to complete the information passed by the label comment.

9. Comment code while writing it (write the code, complete the comment)

Write the code and add comments at the same time, because you have the clearest idea at this point. If you leave the annotated task at the end, then you have experienced two encodings. "I don't have time to comment" "I'm Too Busy" "project delayed" These are often reasons for not writing comments. So, programmers believe that the best solution is to ' write a comment before writing the code '. For example:

public void ProcessOrder ()

{

Make sure, the products is available

Check the customer is valid

Send the order to the store

Generate Bill.

}

Write comments as if they were for your (in fact, they is) think of the code reader as yourself (as is often the case)

Commenting on the code is not just for those who might maintain your code in the future, but it's probably you to read the comments. The great Phil Haack said: "Every time a line of code is knocked on the screen, you have to look at the code from a maintenance perspective." "as soon as a line of code are laid on the screens, you're ' re in maintenance mode on that piece of code." (the famous words dare not enclose the original sentence)

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

One. Update comments when you update the code (remember to refresh the comments when updating the codes)

If comments cannot be updated as the code is updated, then even an accurate comment is meaningless. The code and comments must be synchronized, otherwise these comments are simply torture to the program staff who maintain your code. When using the refactoring tool to automatically update code, it is important to note that they automatically update the code without changing the annotations, which naturally expire.

The golden Rule of comments:readable code (good readability is the best comment)

For many programmers, one of the basic principles is to let the code speak for itself. One might suspect that this is an excuse for programmers who do not like to write annotations, but this is indeed an indisputable fact. Self-explanatory code is good for coding, and not only is it easy to understand and even make annotations unnecessary. For example, in my article "Fluid Interfaces", I show what a clear 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 case, the comment is not necessary and will violate the tip#4. To make the code more readable, you should consider using the appropriate name (as described in the classic Ottinger's rules) to ensure proper indentation and code style bars (code style bars are similar to #region #endregion这类的东西吧? ）。 If this is not a good thing, the immediate consequence is that your comments look like you're apologizing for the obscure code.

You may also have personal experience, no annotated code, would you like to see it? A good habit determines your future.

From: http://blog.csdn.net/yi_zz/article/details/8200897

13 Tips for Writing program notes (GO)