锐客网

  1. 首页 > 睿知 > it技术 > >

函数注释c语言标准格式化 c语言注释掉是什么意思( 二 )

IT技术喷发


Calls:// 被本函数调用的函数清单
Called By:// 调用本函数的函数清单
Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）
Table Updated:// 被修改的表（此项仅对于牵扯到数据库操作的程序）
Input:// 输入参数说明，包括每个参数的作
// 用、取值说明及参数间关系 。
Output:// 对输出参数的说明 。
Return:// 函数返回值的说明
Others:// 其它说明
*************************************************/
5：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性 。不再有用的注释要删除 。
6：注释的内容要清楚、明了，含义准确，防止注释二义性 。
说明：错误的注释不但无益反而有害 。
7：避免在注释中使用缩写，特别是非常用缩写 。
说明：在使用缩写时或之前，应对缩写进行必要的说明 。
8：注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开 。
示例：如下例子不符合规范 。
例1：
/* get replicate sub system index and net indicator */
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;
/* get replicate sub system index and net indicator */
应如下书写
/* get replicate sub system index and net indicator */
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
9：对于所有有物理含义的变量、常量 ， 如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义 。变量、常量、宏的注释应放在其上方相邻位置或右方 。
示例：
/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000
#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */
10：数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释 。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方 。
示例：可按如下形式说明枚举/数据/联合结构 。
/* sccp interface with sccp user primitive message name */
enumSCCP_USER_PRIMITIVE
{
N_UNITDATA_IND, /* sccp notify sccp user unit data come */
N_NOTICE_IND,/* sccp notify user the No.7 network can not */
/* transmission this message */
N_UNITDATA_REQ, /* sccp user's unit data transmission request*/
};
11：全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明 。
示例：
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */// 变量作用、含义
/* 0 － SUCCESS1 － GT Table error */
/* 2 － GT errorOthers － no use*/// 变量取值范围
/* onlyfunctionSCCPTranslate() in */
/* this modual can modify it,andother */
/* module can visit it through call */
/* thefunction GetGTTransErrorCode() */// 使用方法
BYTE g_GTTranErrorCode;
12：注释与所描述内容进行同样的缩排 。
说明：可使程序排版整齐，并方便注释的阅读与理解 。
示例：如下例子，排版不整齐，阅读稍感不方便 。
void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */
CodeBlock Two
}
应改为如下布局 。
void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */

推荐阅读


上一篇：postgresql中建表，postGreSQL表分析

下一篇：网页游戏即时战略，网页游戏即时战略怎么玩