1. Function name, variable name, file name should be descriptive; less abbreviations.
As much as possible to give a descriptive name, do not love the space, after all, let the code easy to understand the new reader is important. Don't use abbreviations that only project developers can understand, and don't abbreviate words by cutting down a few letters.
Good code:
int price_count_reader; No abbreviations
int num_errors; "Num" would have been very common.
int num_dns_connections; Everybody knows what "DNS" is.
Bad code.
int n; Somehow.
int nerr; Strange abbreviations.
int N_comp_conns; Strange abbreviations.
int wgc_connections; Only your team knows what it means.
int pc_reader; There are too many possible explanations for "PC".
int cstmr_id; Some letters have been truncated.
The variable names are lowercase, and the words are concatenated with underscores. The member variable of the class ends with an underscore, but the struct does not
Good code:
string table_name; Available-underline.
String TableName; Available-All lowercase.
Bad code:
String TableName; Poor-mixed case.
2. Note: The function of the note is to compensate for the lack of expression in the code itself;
While annotations are important, the best code itself should be self-documenting. Meaningful type names and variable names are far better than ambiguous names to be interpreted with annotations.
Variable Comment:
Usually the variable name itself is good enough to explain the purpose of the variable. In some cases, additional explanatory notes are also required.
Function Comment:
function declaration Note describes function function; The definition describes the function implementation.
function declaration:
Annotations describe the function and usage of functions before they are declared. Note Use narrative ("Opens the file") rather than instruction ("Open the File"); Comments are just to describe the function, not what the command function does. Typically, annotations do not describe how a function works. That is the function definition part of the thing.
The contents of the comment at the function declaration:
The input and output of the function.
For class member functions: Whether the object needs to persist the reference parameter during a function call, and whether the arguments are disposed.
If the function allocates space, it needs to be freed by the caller.
Whether the parameter can be NULL.
Whether there is a performance hazard on function usage.
If the function is reentrant, what is the synchronization prerequisite?
Implementation notes:
Comment on the smart, obscure, interesting, important places in the code.
Line Comment:
A more obscure place to add comments at the end of a line. Two blank lines at the end of the line are commented.
For more information, refer to
Google Kaiyuan Project style guide
http://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/
Variable Naming and annotation
