Mastering C/C++ Comment Standards: A Complete Guide to Effective Code Documentation

1. Comment Style

Overview

Use // or /* */ consistently across the project.

Details

Both single‑line ( //) and block ( /* */) comments are acceptable; the key is to enforce a uniform style within the team.

2. File Comments

Overview

Each file should start with a header containing copyright, author, creation date, and a brief description.

Details

If a file only declares a single entity that is already documented elsewhere, a file header is optional; otherwise, include it.

Legal and License

Include a license reference (e.g., Apache 2.0, BSD, LGPL, GPL) and choose the appropriate version for the project.

/************************************************************************
*    Copyright 2020 Google Inc.
*    File Name: <filename>
*    Description: <description>
*
*    Version: V1.0
*    Author: Your_Name
*    Create Time: 2020-01-01
*************************************************************************/

3. Function Comments

Overview

Comment the function declaration to describe its purpose; comment the definition to explain the implementation.

Details

Every function should have a brief comment before its declaration, unless its behavior is trivial (e.g., simple getters/setters). For complex logic, add explanatory notes in the definition.

/************************************************************************
*    Function Name: <function_name>
*    Function Purpose: <description>
*    Input Parameters: void
*    Output Parameters: void
*    Return Value: void
*
*    Author: Your_Name
*    Creation Time: 2020-01-01
*    Additional Notes: None
*    Modification History: None
************************************************************************/

4. Variable Comments

Overview

Variable names should be self‑explanatory, but additional comments are sometimes necessary.

Details

Distinguish between global and local variables: local variables usually need only brief comments, while global variables, which affect multiple files, require more detailed explanations. Minimize the use of global variables.

5. Spelling Comments

Overview

Complex names or concepts should be documented with full sentences that include proper capitalization and punctuation.

Details

Complete sentences improve readability; short end‑of‑line comments are acceptable if they follow a consistent style, and correct spelling, commas, and periods are essential.

6. TODO Comments

Overview

Use TODO for temporary or imperfect code sections.

Details

Write TODO in uppercase, followed by parentheses containing the author’s name, email, bug ID, or related issue. This standardized format helps others locate and address pending tasks.

7. Conclusion

While comments are important, the best code is self‑documenting; meaningful type and variable names often eliminate the need for extensive comments. Write comments generously for the next reader, who may be yourself.