一、文章来由

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

（注：每个人的习惯不同，可找到自己喜欢的注释风格）

二、具体规范

有的项目可能要求注释占到总行数的额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]