1.一般情况下，源程序有效注释量必须在 20％以上：
说明：注释不宜太多也不能太少，注释语言 必须准确、易懂、简洁
2.在文件的开始部分，应该给出关于文件版权、内容简介、修改历史等项目的说明。
具体的格式请参见如下的说明。在创建代码和每次更新代码时，都必须在文件的历史记录中标注版本号、 日期、作者、更改说明等项目。其中的版本号的格式为两个数字字符和一个英文字母字符。数字字符表示
大的改变，英文字符表示小的修改。如果有必要，还应该对其它的注释内容也进行同步的更改。注意：注释第一行星号要求为 76 个,结尾行星号为 1 个
/***************************************************************************** Copyright (C), 2010-2011,武汉汉升汽车传感系统有限责任公司* 文件名: main.c* 内容简述：** 文件历史：* 版本号 日期 作者 说明* 01a 2010-07-29 王江河 创建该文件* 01b 2010-08-20 王江河 改为可以在字符串中发送回车符* 02a 2010-12-03 王江河 增加文件头注释*/
3.对于函数，在函数实现之前，应该给出和函数的实现相关的足够而精练的注释信息。内容包括函数功能介绍，调用的变量、常量说明，形参说明，特别是全局、全程或静态变量（慎用静态变量），要求对其初值，调用后的预期值作详细的阐述。具体的书写格式和包含的各项内容请参见如 下的例子
示例：
/***************************************************************************** 函数名: SendToCard()* 功 能: 向读卡器发命令，如果读卡器进入休眠，则首先唤醒它* 输 入: 全局变量 gaTxCard[]存放待发的数据* 全局变量 gbTxCardLen 存放长度* 输 出: 无*/
4.边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
5.注释的内容要清楚、明了，含义准确，防止注释二义性。
说明：错误的注释不但无益反而有害。注释主要阐述代码做了什么（What），或者如果有必要的话，阐述 为什么要这么做（Why），注释并不是用来阐述它究竟是如何实现算法（How）的。
6.避免在注释中使用缩写，特别是非常用缩写
说明：在使用缩写时或之前，应对缩写进行必要的说明。
7.注释应与其描述的代码靠近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置， 不可放在下面，如放于上方则需与其上面的代码用空行隔开。
示例：如下例子不符合规范。
eg1:
eg2:
规范的写法:
eg3:
不规范的写法，显得代码过于紧凑
eg4:
规范写法：
eg5:
8.注释与所描述内容进行同样的缩排。
说明：可使程序排版整齐，并方便注释的阅读与理解。
eg1：如下例子，排版不整齐，阅读稍感不方便。
eg2: 正确的布局
9.对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程 序，有时甚至优于看设计文档
10. 对于 switch 语句下的 case 语句，如果因为特殊情况需要处理完一个 case 后进入下一个 case 处理，必须在该 case 语句处理完、下一个 case 语句前加上明确的注释。
说明：这样比较清楚程序编写者的意图，可有效防止无故遗漏 break 语句。
eg
11.注释格式尽量统一，建议使用“/* …… */”，因为 C++注释“//”并不被所有 C 编译器支持。
12. 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能非常流利准确的用英文表达
13. 标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。
说明：较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些
单词有大家公认的缩写。
示例：如下单词的缩写能够被大家基本认可。
temp 可缩写为 tmp;
flag 可缩写为 flg;
statistic 可缩写为 stat;
increment 可缩写为 inc;
message 可缩写为 msg;
14.命名中若使用特殊约定或缩写，则要有注释说明。
说明：可在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说明。
15.自己特有的命名风格，要自始至终保持一致，不可来回变化。
说明：个人的命名风格，在符合所在项目组或产品组的命名规则的前提下，才可使用。（即命名规则 中没有规定到的地方才可有个人命名风格）。
16. 对于变量命名，禁止取单个字符（如 i、j、k...），建议除了要有具体含义外，还能表明其变量类型、 数据类型等，但 i、j、k 作局部循环变量是允许的。
说明：变量，尤其是局部变量，如果用单个字符表示，很容易敲错（如i写成j），而编译时又检查不出 来，有可能为了这个小小的错误而花费大量的查错时间
17.命名规范必须与所使用的系统风格保持一致，并在同一项目中统一，比如采用 UNIX 的全小写加下划线的风格或大小写混排的方式，不要使用大小写与下划线混排的方式，用作特殊标识如标识 成员变量或全局变量的 m_和 g_，其后加上大小写混排的方式是允许的。
示例： Add_User不允许，add_user、AddUser、m_AddUser允许。
18. 除非必要，不要用数字或较奇怪的字符来定义标识符。
19.在同一软件产品内，应规划好接口部分标识符（变量、结构、函数及常量）的命名，防止编译、 链接时产生冲突。
说明：对接口部分的标识符应该有更严格限制，防止冲突。如可规定接口部分的变量与常量之前加上 “模块”标识等。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
