个人C++注释规范

一、文章来由

好久没写博客了，最近都在做项目，在做项目的过程中遇到多种注释的问题，现在就理清一个注释规范，以后我就按照这个规范来注释~~养成好的注释习惯有助于提高代码的可读性
（注：每个人的习惯不同，可找到自己喜欢的注释风格）

二、具体规范

有的项目可能要求注释占到总行数的额50%。

2.1 源文件头部注释

Ø 列出：作者、编写日期和描述。
Ø 示例：

/* 
* Copyright:bupt
* funtion: 端口选择器实体
* Date:2015-09-01
* Author: Bill Wang
*/

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

2.2 函数头部注释

Ø 列出：功能、输入参数、输出参数、返回值、调用关系（函数、表）等。
Ø 示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议
要包含在内。

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

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

这个就是最常见的注释，可用多个斜杠引起注意

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

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

/////!!!端口选择器类型
enum WinSwitcherType{
    WS_NONE = 0, //不显示
    WS_NAME, //名字
    WS_PORT_SINGLE,//单端口
    WS_PORT_DOUBLE,//双端口
    WS_VALUE_TEXT,//值 文本
    WS_VALUE_INT,//值 数字 整型
    WS_VALUE_DOUBLE,//值 数字 浮点型
    WS_VALUE_BOOL,//值 文本
    WS_FILW_PATH, //文件路径
    WS_INPORT //端口输入
};

3.4 全局变量的注释

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

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

—END—

---

参考文献

[1] http://blog.csdn.net/lincyang/article/details/6020785