Google C + + Programming style Guide (vi): code comments

Comments

Annotations are painful to write, but are important to ensure the readability of the code, and the following rules describe what should be commented on and where the comment is. Remember, of course, that annotations are really important, but the best code in itself is the document (self-documenting), and the type and variable naming sense is much better than the ambiguous naming through annotations.

Comments are written for someone else (the next person who needs to understand your code), seriously, the next person may be you!

1. Annotation style (Comment style)

Use//////* *, unified.

OR//* * can be,//only used more widely, in how annotation and annotation style to ensure unity.

2. Document annotation (file Comments)

Add a copyright notice at the beginning of each file, followed by a description of the file content.

Legal notices and author information:

Each file contains the following items, followed by:

1 Copyright (statement): such as copyright 2008 Google Inc.;

2) licensed version (license boilerplate): Select the appropriate license version for the project, such as Apache 2.0, BSD, LGPL, GPL;

3 Author (author line): Identifies the original author of the file.

If you make a significant change to a file created by someone else, add your information to the author's message so that anyone who has questions about the file can know who to contact.

File contents:

After each file copyright license and author information, the contents of the file should be annotated.

Typically, the. h file has a simple description of the functionality and usage of the declared class. The CC file contains more implementation details or algorithmic discussions, and if you feel that the implementation details or algorithmic discussions are helpful for reading, you can put the comments in. h in. CC and point out the document in. h.

Instead of copying annotations between. h and. CC, the copied annotations deviate from the actual meaning.

3. Class annotations (classes Comments)

The definition of each class adheres to a comment describing the function and usage of the class.

// Iterates over the contents of a GargantuanTable.Sample usage:
// GargantuanTable_Iterator* iter = table->NewIterator();
// for (iter->Seek("foo"); !iter->done(); iter->Next()) {
// process(iter->key(), iter->value());
// }
// delete iter;
class GargantuanTable_Iterator {
...
};

If you think you've already described the class in detail at the top of the file, you want to simply come up with a "full description of the top of the file," or how much to add a note to the class.

If the class has any synchronization prerequisites (synchronization assumptions), the documentation describes it. If an instance of the class can be accessed by multithreading, be sure to note the documentation when you use it.