C++编码规范

c++编码规范 V1.2

【规则3-2】 源文件.cpp、头文件.h文件及其它说明性文件头部必须进行注释，注释如

下格式所示。

/** @file 程序文件名称（如ByteBuffer.cpp） @brief 程序文件的简要说明 程序文件的详细说明（简要与详细说明之间间隔一个空行） @author 作者姓名 @version 版本编号 修订日期 修订者 修订内容 */ 注： ? 注释必须以“/**”开头 ? 允许存在多个@version指示符描述版本修订历程（每个@version指示符描述一个版本）

【规则3-3】 源程序模块函数接口（允许在其它模块使用的函数）必须注释，注释如下

格式所示。

/** @brief 函数的简要说明 函数的详细说明（简要与详细说明之间间隔一个空行） @param 参数名称 参数说明 @return 返回值说明 @retval 值 返回值具体单个值说明 */ 注： ? 注释必须以“/**”开头 ? 注释必须置于函数定义原型之上 ? 允许存在多个@param指示符描述多个参数（每个@param指示符描述一个参数） ? 允许存在多个@retval指示符描述多个具体的返回值说明（每个retval指示符描述一个返回值） ? @param、@return、@retval指示符均是可选项

【规则3-4】 源程序模块内部函数接口（即模块内部的私有函数）可以不必注释，一旦

注释，采取如下格式所示。

Page 5 of 10

c++编码规范 V1.2

/* @brief 函数的简要说明 函数的详细说明（简要与详细说明之间间隔一个空行） @param 参数名称 参数说明 @return 返回值说明 @retval 值 返回值具体单个值说明 */ 注： ? 注释必须以“/*”开头 ? 注释必须置于函数定义原型之上 ? 允许存在多个@param指示符描述多个参数（每个@param指示符描述一个参数） ? 允许存在多个@retval指示符描述多个具体的返回值说明（每个retval指示符描述一个返回值） ? @param、@return、@retval指示符均是可选项 ? 对于一些非常简单的模块内部私有函数可以使用简单注释，不作强制规范要求

【规则3-5】 源程序模块变量接口（允许在其它模块使用的变量）必须注释，注释如下

格式所示（有两种注释格式）。

格式一： /** @brief 变量的简要说明 变量的详细说明（简要与详细说明之间间隔一个空行） */ 注： ? 注释必须以“/**”开头 ? 注释必须置于变量定义之上

格式二： ///< 变量的说明 注： ? 注释必须以“///<”开头 ? 注释必须置于变量定义之后，与变量定义处于同一行

【规则3-6】源程序模块内部变量接口（即模块内部的私有变量）可以不必注释，一旦

Page 6 of 10

c++编码规范 V1.2

注释，采取如下格式所示（有两种注释格式）。

格式一： /* @brief 变量的简要说明 变量的详细说明（简要与详细说明之间间隔一个空行） */ 注： ? 注释必须以“/*”开头 ? 注释必须置于变量定义之上

格式二： // 变量的说明 注： ? 注释必须以“//”开头 ? 注释必须置于变量定义之后，与变量定义处于同一行

【规则3-7】 源程序模块自定义类型必须注释（含结构、C＋＋类等），注释如下格式所

示。

/** @brief 类型的简要说明 类型的详细说明（简要与详细说明之间间隔一个空行） */ 注： ? 注释必须以“/**”开头 ? 注释必须置于类型定义之上 ? 对子元素的注释可参照对函数、变量的注释格式

【规则3-8】 一般情况下，源程序有效注释量必须达到20％以上。

【规则3-9】 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一

致性。不再有用的注释要删除。

【规则3-10】 注释的内容要清楚、明了，含义准确，防止注释二义性。说明：错误的

注释不但无益反而有害。

Page 7 of 10

c++编码规范 V1.2

【规则3-11】 避免在注释中使用缩写，特别是非常用缩写。说明：在使用缩写时或之

前，应对缩写进行必要的说明。

【规则3-12】 注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单

条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

【规则3-13】 对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在

【规则3-14】

【规则3-15】

【规则3-16】

【规则3-17】

【规则3-18】

【规则3-19】

【规则3-20】

【规则3-21】

【规则3-22】

声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。

数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自

注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。

全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过

程存取它以及存取时注意事项等的说明。

注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便

注释的阅读与理解。

将注释与其上面的代码用空行隔开。 对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。说

明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

对于switch语句下的case语句，如果因为特殊情况需要处理完一个

case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。

避免在一行代码或表达式的中间插入注释。说明：除非必要，不应在代

码或表达式中间插入注释，否则容易使代码可理解性变差。

通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结

构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

在代码的功能、意图层次上进行注释，提供有用、额外的信息。说明：

注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。

Page 8 of 10