在C++项目开发中，注释不仅是给自己看的笔记，更是团队协作和后期维护的重要依据。清晰的注释规范能降低理解成本，减少沟通误差。下面我们先看一张示意图，再展开具体的规范内容。
一、C++注释的基本语法
C++本身支持两种原生注释形式，所有代码文件和头文件中都可以使用。
- 单行注释：以
//开头，直到行尾结束。 - 多行注释：以
/*开头，以*/结尾，可跨多行。
示例代码如下：
#include <iostream>
// 这是单行注释，用于说明下面函数的作用
int add(int a, int b) {
/* 这是多行注释
用来描述具体实现思路
返回两数之和 */
return a + b;
}
int main() {
std::cout << add(1, 2) << std::endl; // 输出结果
return 0;
}
二、文件与函数的注释规范
在实际工程中，通常要求每个源文件和头文件开头写明版权、作者与功能概述。函数前应使用统一格式说明用途、参数和返回值。
1. 文件头注释
文件顶部用多行注释简要说明模块职责，例如：
/* * 文件名：math_util.cpp * 功能：基础数学工具函数实现 * 作者：dev */
2. 函数注释
函数声明或定义上方写清楚输入与输出，避免只写废话。比如：
// 计算两个整数的最大值 // 参数：a 第一个整数，b 第二个整数 // 返回：两者中较大的值 int max(int a, int b);
三、Doxygen风格注释
如果团队使用Doxygen生成文档，可以采用特殊标记注释，以 /** 开头的块会被工具识别。
/** * @brief 计算阶乘 * @param n 非负整数 * @return n的阶乘 */ int factorial(int n);
四、注释编写的建议
注释规范的核心不是写得多，而是写得准。下面几条建议比较实用：
- 不要注释显而易见的代码，比如
i++;后面写"i自增"。 - 说明为什么这么做，而不是重复代码做了什么。
- 及时删除过时注释，避免误导。
- 复杂逻辑块前用简短注释概括意图。
| 注释类型 | 适用场景 | 推荐写法 |
|---|---|---|
| 单行注释 | 临时说明、行尾补充 | // 说明文字 |
| 多行注释 | 文件头、逻辑段描述 | /* ... */ |
| Doxygen | 公开接口文档 | /** ... */ |
五、小结
遵循统一的C++注释规范，可以让代码更易读、易维护。从基本语法到文件函数说明，再到文档化注释，层层递进地培养好习惯，是每一个C++开发者应有的素养。