C # Coding specifications summarized by myself-5. How to Write comments

This article is a practical method for writing comments after reading several books mentioned in the preface and combining their own ideas:

• How to write comments
• Avoid using ambiguous pronouns

In some cases, pronouns such as "it" and "this" are prone to ambiguity. The safest way is not to replace all Pronouns that may be ambiguous with actually referred words.

For example: // Insert the data into the cache, but check if it's too big first.

"It" refers to "data" or "cache "? No one knows who it refers to before reading the remaining code. What else do I need to comment out? After you replace it with the word you want to refer to, the reader can directly know what to do next in the code.

// Insert the data into the cache, but check if the data is too big first.

• Accurately describe the behavior of a Method

Annotations must accurately describe the behavior of methods. Avoid incorrect calls due to incorrect annotations.

If you write a method to count the number of rows in the file

// Return the number of lines in this file

Public long countlinesinfile (string filename)

The comment above is not very accurate, because there are many ways to define rows. In the following situations, the return values of this method cannot be quickly determined based on the comment.

1. "" (Empty file) -- 0 or 1 line?
2. "Hello" -- 0 or 1 line?
3. "Hello \ n" -- 1 or 2 rows?
4. "Hello \ n \ r world \ r" -- 2, 3, or 4 rows?

Assuming that the implementation of this method is to count the number of line breaks (\ n), the following comments are better than the original comments.

// Count how many newline symbols ('\ n') are this file

This comment contains more information. The reader can know that if there is no line break, this function will return 0. The reader also knows that the carriage return (\ r) will be ignored.

• Use Input and Output examples to illustrate special situations

For comments, a well-selected example is more effective than a thousand words, more straightforward and effective, and faster reading.

For example: // <summary>

/// Remove the suffix/prefix of charstoremove from the Input Source

/// </Summary>

Public String stripprefixandsuffix (string source, string charstoremove)

This comment is not very accurate because it cannot answer the following questions.

1. Is it true that only characters in the order of charstoremove will be removed, or will unordered charstoremove be removed?
2. What if there are multiple charstoremoves at the beginning and end?

In a good example, you can simply answer these questions:

/// <Summary>

/// Example: stripprefixandsuffix ("abbayabbazbaba", "AB") returns "yababz"

/// </Summary>

• Use the name function as appropriate

Suppose you see such a function call:

Connectmailserver (100, false );

It is difficult to understand this call because the values and bool values are passed in directly. In this case, you can use the C # name function so that the code reader can quickly understand the meanings of these two parameters.

Assume that the function is like this: Public void connectmailserver (INT timeout_s, bool useencryption)

Then we can use the name function as follows:

Connectmailserver (timeout_s: 100, useencryption: false );

The code reader can see the functions of these two parameters at a glance.

• Use General terminology

The reader and caller of the Code are both programmers. There are a lot of special terms between the programmers that can be used to describe some patterns and solutions. Using these words can give a simple and clear explanation of the meaning of your code.

Assume that your original comment is as follows:

You can simply say:

// This class acts asCaching LayerTo the database.

The programmer can understand what the caching layer is doing. Even if a newbie doesn't understand it, it's hard to explain your comments to him. It's better to give him a keyword to Google or ask someone else. This effect is much better than your comments.

• Remember to update comments when updating code

Even better comments will become meaningless as the content changes. Sometimes, they may even mislead readers and generate unnecessary bugs. After changing the code, remember to update the comments of the changed code to express the meaning of the latest code.

• Only comments that can be read by others are qualified comments.

When you are not sure whether your comments are qualified, ask your colleagues around you to read your comments and see if they want to express their ideas after reading the comments, whether information is missing or misunderstood.