常见C/C++编码规范(2)

 

2.2. 可理解性 
2.2.1.注释 
注释的原则是有助于对的阅读理解,注释不宜太多也不能太少,太少不利于理解,太多则会对阅读产生干扰,因此只在必要的地方才加注释,而且注释要准确、易懂、尽可能简洁。注释量一般控制在30%到50%之间。 

<规则1> 程序在必要的地方必须有注释,注释要准确、易懂、简洁。 
例如如下注释意义不大。 
/* 如果bReceiveFlag 为 TRUE */ 
if ( bReceiveFlag == TRUE) 

而如下的注释则给出了额外有用的信息。 
/* 如果mtp 从连接处获得一个消息*/ 
if ( bReceiveFlag == TURE) 

<规则2> 注释应与其描述的代码相近,对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 
示例：如下例子不符合规范。 
例子1 
/* 获得系统指针和网络指针的副本 */ 


nRepssnInd = SsnData[ index ].nRepssnIndex ; 
nRepssnNi = SsnData[ index ].ni ; 

例子2 
nRepssnInd = SsnData[ index ].nRepssnIndex ; 
nRepssnNi = SsnData[ index ].ni ; 
/*获得系统指针和网络指针的副本 */ 

应如下书写 
/*获得系统指针和网络指针的副本 */ 
nRepssnInd = SsnData[ index ].nRepssnIndex ; 
nRepssnNi = SsnData[ index ].ni ; 

<规则3> 对于所有的常量,变量,数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,在声明时都必须加以注释,说明其含义。 
示例： 
/* 活动任务的数量 */ 
#define MAX_ACT_TASK_NUMBER 1000 

#define MAX_ACT_TASK_NUMBER 1000 /*活动任务的数量 */ 

/* 带原始用户信息的SCCP接口 */ 
enum SCCP_USER_PRIMITIVE 
{ 
N_UNITDATA_IND , /* 向SCCP用户报告单元数据已经到达 */ 
N_UNITDATA_REQ , /* SCCP用户的单元数据发送请求 */ 
} ; 

<规则4> 头文件、源文件的头部,应进行注释。注释必须列出：文件名、作者、目的、功能、修改日志等。 
例如： 
/********************************************* 
文件名： 
编写者： 
编写日期： 
简要描述：