C语言编码规范 3 --注释


扩展阅读链接


C语言编码规范 1--文件与目录                         https://blog.csdn.net/RootCode/article/details/93221475

C语言编码规范 2--排版                                   https://blog.csdn.net/RootCode/article/details/93222263

C语言编码规范 4 --可读性                               https://blog.csdn.net/RootCode/article/details/93226117

C语言编码规范 5--变量、结构、常量、宏        https://blog.csdn.net/RootCode/article/details/93226847

C语言编码规范 6--函数                                   https://blog.csdn.net/RootCode/article/details/93227533

程序员常用单词汇总                                        https://blog.csdn.net/RootCode/article/details/93748701

 


(1) 一般情况下,源程序有效注释量必须在 20%以上。

说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。

(2) 在文件的开始部分,应该给出关于文件版权、内容简介、修改历史等项目的说明。
具体的格式请参见如下的说明。在创建代码和每次更新代码时,都必须在文件的历史记录中标注版本号、日期、作者、更改说明等项目。其中的版本号的格式为两个数字字符和一个英文字母字符。数字字符表示大的改变,英文字符表示小的修改。如果有必要,还应该对其它的注释内容也进行同步的更改。注意:注释第一行星号要求为 76 个,结尾行星号为 1 个。

/****************************************************************************
* Copyright (C), 2010-2011,xxxx-xxxx有限责任公司
* 文件名: 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[index].repssn_index;
repssn_ni = ssn_data[index].ni;

例 2:不规范的写法

repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
/* 获取复本子系统索引和网络指示器 */             <---- 不规范的写法,应该在语句前注释


例 3:规范的写法

/* 获取复本子系统索引和网络指示器 */
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].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 语句。
示例(注意斜体加粗部分):

C语言编码规范 3 --注释_第1张图片

(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_之类以下划线开始和结尾的定义。

你可能感兴趣的:(C,/,C++语言)