安富莱C语言编码规范 3 --注释
本帖最后由 席萌0209 于 2018-3-19 16:44 编辑安富莱C语言编码规范 3 --注释（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） 注释应与其描述的代码靠近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
示例：如下例子不符合规范。
例 1：不规范的写法
/* 获取复本子系统索引和网络指示器 */
<---- 不规范的写法，此处不应该空行
repssn_ind = ssn_data.repssn_index;
repssn_ni = ssn_data.ni;
例 2：不规范的写法
repssn_ind = ssn_data.repssn_index;
repssn_ni = ssn_data.ni;
/* 获取复本子系统索引和网络指示器 */ <---- 不规范的写法，应该在语句前注释
例 3：规范的写法
/* 获取复本子系统索引和网络指示器 */
repssn_ind = ssn_data.repssn_index;
repssn_ni = ssn_data.ni;
例 4：不规范的写法，显得代码过于紧凑
/* code one comments */
program code one
/* code two comments */ <---- 不规范的写法，两段代码之间需要加空行
program code two
例 5：规范的写法
/* code one comments */
program code one
/* code two comments */
program code two
（8） 注释与所描述内容进行同样的缩排。
说明：可使程序排版整齐，并方便注释的阅读与理解。
例 1：如下例子，排版不整齐，阅读稍感不方便。
void example_fun( void )
{
/* code one comments */ <---- 不规范的写法，注释和代码应该相同的缩进
CodeBlock One
/* code two comments */ <---- 不规范的写法，注释和代码应该相同的缩进
CodeBlock Two
}
例 2：正确的布局。
void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */
CodeBlock Two
}
（9） 对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
（10） 对于 switch 语句下的 case 语句，如果因为特殊情况需要处理完一个 case 后进入下一个 case 处理，必须在该 case 语句处理完、下一个 case 语句前加上明确的注释。
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏 break 语句。
示例（注意斜体加粗部分）：
（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） 除非必要，不要用数字或较奇怪的字符来定义标识符。
示例：如下命名，使人产生疑惑。
uint8_t dat01;
void Set00(uint_8 c);应改为有意义的单词命名。
uint8_t ucWidth;
void SetParam(uint_8 _ucValue);
（19） 在同一软件产品内，应规划好接口部分标识符（变量、结构、函数及常量）的命名，防止编译、链接时产生冲突。
说明：对接口部分的标识符应该有更严格限制，防止冲突。如可规定接口部分的变量与常量之前加上“模块”标识等。
（20） 除了编译开关/头文件等特殊应用，应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义。
注释规范，学习了，谢谢 开始接触安富莱的程序，感觉自己像是发现了宝藏...
很佩服安富莱这种真正沉下来做技术的。 函数头版本信息面向学习者是合适的，实际开发，最好是Git版本控制，可追溯功能强，函数头写再多，不与上一版的比较，很难理解
页:
[1]