C++文件注释规范详解

C++ 文件注释常见规范

一、文件头部注释

核心内容

• 版权声明 ：明确代码的版权归属（如 Copyright (C) [公司 / 作者名]）。
• 作者信息 ：标注主要贡献者（@author 或 Author）。
• 日期与版本 ：记录创建或修改日期（@date），以及版本号（@version）。
• 功能描述 ：简述文件的核心功能（@brief 或 Description）。

示例

/*!  
 * @file Example.cpp  
 * @brief 示例文件，演示基本注释规范  
 * @author John  
 * @date 2025-03-28  
 * @version 1.0  
 */  

格式要求

• 多行注释使用 /*! */ 或 /** */（支持 Doxygen 解析）。
• 每行不超过 80 字符，保持可读性。

二、函数注释规范

关键标签

• 功能说明 ：@brief 描述函数作用。
• 参数说明 ：@param 解释每个参数的意义及约束。
• 返回值 ：@return 或 @retval 说明返回值的含义（如错误码解析）。
• 异常信息 ：@exception 列出可能抛出的异常。

示例

/**  
 * @brief 计算两个整数的和  
 * @param a 第一个加数  
 * @param b 第二个加数  
 * @return 两数之和  
 */  
int add(int a, int b) {  
    return a + b;  
}  

格式要求

• 函数注释紧邻函数定义上方，使用 /** */ 或 /// 风格。

三、代码块与行内注释

行内注释

• 单行注释以 // 开头，置于代码行尾或上方，解释简短逻辑。

示例

int x = 10;  // 初始化变量 x

多行注释

• 复杂逻辑使用 /* */ 包裹，置于代码块上方，解释整体逻辑或算法。

示例

/*  
 * 快速排序算法实现：  
 * 1. 选择基准值  
 * 2. 分割数组  
 * 3. 递归排序子数组  
 */  
void quickSort(int arr[], int low, int high) { ... }  

预处理注释

• 使用 #if 0 ... #endif 临时禁用代码块，便于调试与版本控制。

四、命名空间与类注释

命名空间

• 使用 @brief 描述其功能，并补充详细说明。

示例

/// @brief 数据处理工具集合  
namespace DataUtils { ... }  

类与结构体

• 类定义前添加注释，说明其职责、成员变量及方法。

示例

/**  
 * @brief 表示二维坐标点  
 * @property x 横坐标  
 * @property y 纵坐标  
 */  
class Point { ... };  

五、其他规范

• Doxygen 兼容性 ：遵循 Doxygen 标签语法（如 @ 符号），便于生成 API 文档。
• 注释风格选择 ：项目统一使用 // 或 /* */，优先 C++ 风格（//）。
• 禁用冗余注释 ：避免对自解释代码（如 i++）添加无意义注释。

完整注释示例

/*!  
 * @file MathUtils.cpp  
 * @brief 数学工具库，提供基础运算函数  
 * @author Alice  
 * @date 2025-03-28  
 * @version 2.1  
 */  

/// @brief 数学工具命名空间  
namespace MathUtils {  
    /**  
     * @brief 计算阶乘  
     * @param n 输入的非负整数  
     * @return n 的阶乘结果  
     * @exception 若 n 为负数，抛出 std::invalid_argument  
     */  
    int factorial(int n) {  
        if (n < 0) throw std::invalid_argument("n must be non-negative");  
        return (n <= 1) ? 1 : n * factorial(n - 1);  
    }  
}