公司内有一个统一的注释规范相当重要,下面的文章转载自:http://hi.baidu.com/buptyoyo/blog/item/fc8bdfee2ea1793326979114.html
最近一直在给项目代码加注释,因为结项有一项工程性的要求是注释占到总行数的额50%,这几天可苦了我们几个。前几天为了统一项目组的注释规范,专门整理了一份,以后可能也用得着,放着备份下。
1 源文件头部注释
Ø 列出:版权、作者、编写日期和描述。
Ø 示例:
每行不要超过80个字符的宽度。
2 函数头部注释
/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
Ø 示例:下面这段函数的注释比较标准,当然,并不局限于此格式,但上述信息建议
要包含在内。
3 数据结构声明的注释(包括数组、结构、类、枚举等)
如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。
Ø 示例:可按如下形式说明枚举/数据/联合结构。
4 全局变量的注释
Ø 包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
示例:
5 对代码的注释
注释总是加在程序的需要一个概括性说明或不易理解或易理解错的地方。注释语言应该简练、易懂而又含义准确,避免二义性;所采用的语种首选是中文,如有输入困难、编译环境限制或特殊需求也可采用英文。注释应与其描述的代码相近,对代码的注释统一放在其上方,避免在一行代码或表达式中间使用注释。上方注释与其上面的代码用空行隔开(较紧凑的代码除外)。
注意:注释应与所描述内容进行同样的缩进。