Mastering C/C++ Comment Standards: A Practical Guide

Comments are crucial for code readability and maintenance; without them, understanding and refactoring legacy code becomes extremely difficult.

General Comment Style

Use // for single‑line comments or /* ... */ for block comments, and keep the style consistent across the project.

File Comments

At the top of each file, include copyright, author, creation date, and a brief description of the file’s purpose. If the file only declares or implements an already well‑documented entity, a file comment may be omitted.

/************************************************************************
*    Copyright 2020 Google Inc.
*    File Name: example.cpp
*    Description: Brief file description
*    Version: V1.0
*    Author: Your_Name
*    Create Time: 2020-01-01
*************************************************************************/

Function Comments

Place a comment before each function declaration describing its purpose; the definition should include implementation details, especially for complex logic.

/************************************************************************
*    Function Name: Foo
*    Function Purpose: Does something important
*    Input Parameters: void
*    Output Parameters: void
*    Return Value: void
*    Author: Your_Name
*    Create Time: 2020-01-01
*************************************************************************/

Variable Comments

Local variables usually need only brief comments, while global variables should have detailed explanations of their role across the codebase. Minimize the use of global variables.

Spelling and Punctuation

Write comments as complete sentences with proper capitalization and punctuation; consistency improves readability.

TODO Comments

Use uppercase TODO followed by parentheses containing the developer’s name, contact, or issue ID to flag temporary or incomplete solutions.

// TODO (JohnDoe, #123): Refactor this algorithm for better performance

Conclusion

While comments are important, the best code is self‑documenting through clear naming and structure; comments should supplement, not replace, good design.