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

C # Coding specifications summarized by myself-5. How to Write comments
How to write comments to avoid the use of ambiguous pronouns. In some cases, "it" and "this" are prone to ambiguity, the safest way is not to replace all possible ambiguous pronouns with actually referred words. For example: // Insert the data into the cache, but check if it's too big first. "it" means "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. to accurately describe the behavior comments of a method, you must accurately describe the behavior of the method. 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, there are many ways to define rows. In the following situations, the return values of this method cannot be quickly determined based on annotations. "" (Empty file) -- 0 or 1 line? "Hello" -- 0 or 1 line? "Hello \ n" -- 1 or 2 rows? "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. The input and output examples are used to illustrate the special situations. For comments, a well-selected example is more effective than a thousand words, and more straightforward and effective, with faster reading speed. 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 question: will the character in the Order in charsToRemove be removed, or will the unordered charsToRemove be removed? What if there are multiple charstoremoves at the beginning and end? In a good Example, you can answer these questions in a simple and straightforward way: // <summary> // Example: StripPrefixAndSuffix ("abbayabbazbaba", "AB ") returns "yababz" // </summary> use the named function appropriately. Suppose you see the 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. Suppose the function is like this: public void ConnectMailServer (int timeout_s, bool useEncryption), then we can use the name function: ConnectMailServer (timeout_s: 100, useEncryption: false ); the code reader can see the functions of these two parameters at a glance. Readers and callers who use the general terminology code are both programmers. There are a large number of terminology between programmers that can be used to describe patterns and solutions, you can briefly and clearly describe the meaning of your code. Suppose your original comment is as follows: CachingLayer, you can simply say: // This class acts as a caching layer to 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. When updating code, remember that updating comments with good comments will become meaningless as the content changes. Sometimes it 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 to read your comments, check whether the ideas you have posted after reading the comments are what you want to express, whether there are information omissions and misunderstandings.