- 【一】注释:
- 1.说明性文件(如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等)头部应进行注释,注释必须列出:版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明。
- 示例:下面这段头文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。
- /************************************************************
- Copyright (C), 1988-1999, Huawei Tech. Co., Ltd.
- FileName: test.cpp
- Author: Version : Date:
- Description: // 模块描述
- Version: // 版本信息
- Function List: // 主要函数及其功能
- 1. -------
- History: // 历史修改记录
- <author> <time> <version > <desc>
- David 96/10/12 1.0 build this moudle
- ***********************************************************/
- 说明:Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。History是修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述。
- 2.函数头部应进行注释,列出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
- 示例:下面这段函数的注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内。
- /*************************************************
- Function: // 函数名称
- Description: // 函数功能、性能等的描述
- Calls: // 被本函数调用的函数清单
- Called By: // 调用本函数的函数清单
- Table Accessed: // 被访问的表(此项仅对于牵扯到数据库操作的程序)
- Table Updated: // 被修改的表(此项仅对于牵扯到数据库操作的程序)
- Input: // 输入参数说明,包括每个参数的作
- // 用、取值说明及参数间关系。
- Output: // 对输出参数的说明。
- Return: // 函数返回值的说明
- Others: // 其它说明
- *************************************************/
- 3.数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方。
- 示例:可按如下形式说明枚举/数据/联合结构。
- /* sccp interface with sccp user primitive message name */
- enum SCCP_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*/
- };
- 4.全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
- 示例:
- /* The ErrorCode when SCCP translate */
- /* Global Title failure, as follows */ // 变量作用、含义
- /* 0 - SUCCESS 1 - GT Table error */
- /* 2 - GT error Others - no use */ // 变量取值范围
- /* only function SCCPTranslate() in */
- /* this modual can modify it, and other */
- /* module can visit it through call */
- /* the function GetGTTransErrorCode() */ // 使用方法
- BYTE g_GTTranErrorCode;
- 【二】标识符命名:
- 1.标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。
- 说明:较短的单词可通过去掉“元音”形成缩写;较长的单词可取单词的头几个字母形成缩写;一些单词有大家公认的缩写。
- 示例:如下单词的缩写能够被大家基本认可。
- temp 可缩写为 tmp ;
- flag 可缩写为 flg ;
- statistic 可缩写为 stat ;
- increment 可缩写为 inc ;
- message 可缩写为 msg ;
- 2.对于变量命名,禁止取单个字符(如i、j、k...),建议除了要有具体含义外,还能表明其变量类型、数据类型等,但i、j、k作局部循环变量是允许的。
- 说明:变量,尤其是局部变量,如果用单个字符表示,很容易敲错(如i写成j),而编译时又检查不出来,有可能为了这个小小的错误而花费大量的查错时间。
- 示例:下面所示的局部变量名的定义方法可以借鉴。
- int liv_Width
- 其变量名解释如下:
- l 局部变量(Local) (其它:g 全局变量(Global)...)
- i 数据类型(Interger)
- v 变量(Variable) (其它:c 常量(Const)...)
- Width 变量含义
- 这样可以防止局部变量与全局变量重名。
- 3.用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
- 说明:下面是一些在软件中常用的反义词组。
- add / remove begin / end create / destroy
- insert / delete first / last get / release
- increment / decrement put / get
- add / delete lock / unlock open / close
- min / max old / new start / stop
- next / previous source / target show / hide
- send / receive source / destination
- cut / paste up / down
- 示例:
- int min_sum;
- int max_sum;
- int add_user( BYTE *user_name );
- int delete_user( BYTE *user_name );
- 4.避免使用不易理解的数字,用有意义的标识来替代。涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的枚举或宏来代替。
- 示例:如下的程序可读性差。
- if (Trunk[index].trunk_state == 0)
- {
- Trunk[index].trunk_state = 1;
- ... // program code
- }
- 应改为如下形式。
- #define TRUNK_IDLE 0
- #define TRUNK_BUSY 1
- if (Trunk[index].trunk_state == TRUNK_IDLE)
- {
- Trunk[index].trunk_state = TRUNK_BUSY;
- ... // program code
- }