What is important when looking at source code? Besides various coding standards, one significant aspect is comments.
Although writing comments can be painful, they are crucial for ensuring code readability. Below, we will discuss how and where to comment.
Commenting Style 1. Overview Generally, use // or /* */; just ensure consistency. 2. Explanation Both // and /* */ are acceptable, but // is more commonly used. Ensure consistency in how comments are written and the style used. File Comments 1. Overview Include copyright, author, date, and other descriptions at the beginning of each file. File comments describe the content of the file. If a file only declares, implements, or tests an object, and that object has been detailed in its declaration, then a file comment is unnecessary. All other files require file comments. 2. Explanation Legal notices and author information: Each file should include a license reference. Choose the appropriate version of the license for the project (Introduction to various global open-source licenses). If you have made significant modifications to the original author’s file, consider removing the original author’s information. 3. File Content If a .h file declares multiple concepts, the file comment should provide a general description of the file’s content and explain the relationships between the concepts. A one to two-line file comment is sufficient, while detailed documentation for each concept should be placed within the respective concepts, not in the file comment. Do not copy comments between .h and .cc files, as such comments deviate from their intended meaning. Function Comments 1. Overview Comments at the function declaration describe the function’s functionality; comments at the definition describe the function’s implementation. 2. Explanation Function Declaration: A comment should generally precede each function declaration, describing the function’s purpose and usage. These comments can be omitted only when the function’s purpose is simple and obvious (e.g., simple getter and setter functions). Function Definition: If clever techniques are used in the function’s implementation, explanatory comments should be added at the function definition. For example, you can explain the programming techniques used, the general steps of implementation, or the reasons for such implementation. For instance, you might explain why the first half of the function requires locking while the second half does not. Do not directly copy comments from the function declaration in the .h file or elsewhere. A brief restatement of the function’s purpose is acceptable, but the focus of the comments should be on how it is implemented. Variable Comments 1. Overview Typically, variable names themselves adequately describe their purpose; in some cases, additional comments are needed. 2. Explanation Variables can be categorized into many types based on different scenarios and modifiers; generally, they are divided into global and local variables. Local variables are usually limited to a local scope, and their meanings are relatively simple and easy to understand, requiring only brief comments. Global variables generally affect multiple files or the entire project, so their meanings are relatively more complex. Therefore, when commenting, it is best to clearly describe their specific meanings, aiming for comprehensive descriptions. (Tip: Minimize the use of global variables) Spelling Comments 1. Overview A variable or function may contain a very complex meaning, requiring multiple words to spell it out; in this case, detailed comments on the spelling content are necessary. 2. Explanation The usual format for comments is a complete narrative statement with correct capitalization and a period at the end. In most cases, complete sentences are more readable than sentence fragments. Shorter comments, such as inline comments, can be more casual, but consistency in style should still be maintained. Additionally, spelling and punctuation in comments are important. While it can be somewhat awkward to be pointed out for using a comma instead of a semicolon, clear and readable code is still crucial. Correct punctuation, spelling, and grammar will greatly assist in this regard. TODO Comments 1. Overview Use TODO comments for temporary, short-term solutions or code that is good enough but still not perfect. TODO comments should use the fully capitalized string TODO, followed by your name, email address, bug ID, or other identifiers related to this TODO in parentheses. The main purpose is to allow the person adding the comment (who can also request more details) to find it based on the standardized TODO format. Adding a TODO comment does not mean you have to fix it yourself, so when you add a TODO with a name, it is generally your own name. Deprecated Comments 1. Overview Use deprecated comments to mark an interface point as deprecated. You can write a comment containing the fully capitalized word DEPRECATED to mark an interface as deprecated. The comment can be placed before the interface declaration or on the same line. After the word DEPRECATED, leave your name, email address, and other identifiers in parentheses. Deprecated comments should include brief and clear guidance to help others fix their calling points. In C++, you can convert a deprecated function into an inline function that calls the new interface. Simply marking an interface as DEPRECATED will not automatically lead everyone to stop using it; you must actively correct the calling points or find someone to help. The corrected code should no longer involve deprecated interface points, and comments should refer to the new interface points. If you are unsure where to start, you can discuss with the person who marked the deprecated comment. Conclusion While comments are indeed important, the best code should serve as documentation itself. Meaningful type names and variable names far outweigh vague names that require comments for explanation. The comments you write are for the code readers, that is, the next person who needs to understand your code. So be generous; the next reader might just be you!