C/C++注释规范

1. 源文件头部注释

列出：版权、作者、编写日期和描述。

示例：

/*************************************************
Copyright:East
Author:Jason
Date:2017-03-02
Description:描述主要实现的功能
**************************************************/

每行不要超过80个字符的宽度。

 

2. 函数头部注释

列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。

示例：

/*************************************************
Function:       // 函数名称
Description:    // 函数功能、性能等的描述
Calls:          // 被本函数调用的函数清单
Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）
Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序）
Input:          // 输入参数说明，包括每个参数的作
                  // 用、取值说明及参数间关系。
Output:         // 对输出参数的说明。
Return:         // 函数返回值的说明
Others:         // 其它说明
*************************************************/

这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

 

3. 数据结构声明的注释(包括数组、结构、类、枚举等)

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

可按如下形式说明枚举/数据/联合结构，示例：

/* sccp interface with sccp user primitive message name */
enum SCCP_USER_PRIMITIVE
{
    N_UNITDATA_IND, /* sccp notify sccp user unit data come */
    N_NOTICE_IND,   /* sccp notify user the No.7 network can not */
                    /* transmission this message */
    N_UNITDATA_REQ, /* sccp user's unit data transmission request*/
};

 

4. 全局变量的注释

包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。

示例：

/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */      // 变量作用、含义

　　

5. 对代码的注释

注释总是加在程序的需要一个概括性说明或不易理解或易理解错的地方。注释语言应该简练、易懂而又含义准确，避免二义性；所采用的语种首选是中文，如有输入困难、编译环境限制或特殊需求也可采用英文。注释应与其描述的代码相近，对代码的注释统一放在其上方，避免在一行代码或表达式中间使用注释。上方注释与其上面的代码用空行隔开（较紧凑的代码除外）。

注意：注释应与所描述内容进行同样的缩进。