C/C++ Commenting Guidelines and Best Practices

If a leader gives you a source code project to read and refactor without any comments, it likely means the previous developer left abruptly; this highlights why comments are essential for code readability.

General comment style in C/C++ typically uses // for single‑line comments or /* */ for block comments; the key is to keep the style consistent across the team.

File Comments Each file should start with a header containing copyright, author, date, and a brief description of the file’s purpose. If the file only declares or implements an already well‑documented object, a file comment may be unnecessary, but otherwise it should be included.

Legal notices and author information, such as license references (e.g., Apache 2.0, BSD, LGPL, GPL), should also be part of the file header.

Function Comments At the function declaration, add comments describing the function’s purpose and usage; at the definition, add comments explaining implementation details, especially for complex logic. Example:

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

/*****
*    函数名：函数名
*    函数功能：功能描述
*    输入参数：void
*    输出参数：void
*    返回值：void
*    作者：Your_Name
*    创建时间：2020-01-01
*    其他说明：无
*    修改信息：无
******/

Variable Comments Variable names should be self‑explanatory, but additional comments are useful when the purpose is not obvious. Local variables usually need brief comments, while global variables, which affect multiple files, should have more detailed explanations. Minimize the use of global variables.

Spelling Comments Comments should be complete sentences with proper capitalization and punctuation. Full sentences improve readability compared to fragments, and consistent style should be maintained throughout the codebase.

TODO Comments Use uppercase TODO tags for temporary or incomplete solutions. Include your name, email, bug ID, or related issue in parentheses after the tag to facilitate tracking. Example: TODO (John Doe, [email protected]): Refactor this loop.

Conclusion While comments are important, the best code is self‑documenting through clear type and variable names. Comments should aid the next reader of the code, so write them generously for future maintainers.