最近一直在处理之前他人留下的代码,很是头疼。因为程序注释性的东西太少了,而且很多不合规范。不过也暴露了自己平时写代码的缺陷。在这里整理了一下程序注释编写规范,留待日后参考。
程序中的注释能够帮助理解程序。但是也不能太多,太多同样会影响程序的可读性。要遵循简练,准确,易理解的原则。

1、文件头:文件的头部应该有个对本文件的详细描述。内容包括版权,版本号,生成日期,作者,内容,功能,函数功能,与其他文件的关系,修改日志等。尤其是每次修改,都应该写入修改日志。

下面是一个常用的模版
/*************************************************
Copyright (C), 2000-2004, ******
File name:      // 文件名
Author:       Version:        Date: // 作者、版本及完成日期
Description:    // 用于详细说明此程序文件完成的主要功能,与其他模块
// 或函数的接口,输出值、取值范围、含义及参数间的控
// 制、顺序、独立或依赖等关系
Others:         // 其它内容的说明
Function List:  // 主要函数列表,每条记录应包括函数名及功能简要说明
1. ….
History:        // 修改历史记录列表,每条修改记录应包括修改日期、修改
// 者及修改内容简述
1. Date:
Author:
Modification:
2. …
*************************************************/

2、函数:列出函数的目的,功能、输入输出、返回值、调用关系等。
模版:
/*************************************************
Function:       // 函数名称
Description:    // 函数功能、性能等的描述
Calls:          // 被本函数调用的函数清单
Called By:      // 调用本函数的函数清单
Table Accessed: // 被访问的表(此项仅对于牵扯到数据库操作的程序)
Table Updated:  // 被修改的表(此项仅对于牵扯到数据库操作的程序)
Input:          // 输入参数说明,包括每个参数的作
// 用、取值说明及参数间关系。
Output:         // 对输出参数的说明。
Return:         // 函数返回值的说明
Others:         // 其它说明
*************************************************/

3、文件内部注释:编写代码的同时应该写出注释,修改代码时应该连同修改注释。保证注释与文件的同步。写注释时应该遵循简洁,准确,明了的原则,尽 量少使 用缩写,尤其是不常用的缩写。注释的位置应该在被注释语句的上方或右方,位于上方时,应该与上方的语句用空行分开。注释应该与被注释语句相同缩进。

4、命名:变量,数据结构等如果命名不是充分自注释的,必须有注释。说明其作用,取值范围,在哪里使用,适用时的注意事项等。

5、语句:分支语句必须给出注释。包括语句块的功能,输出。程序块结束行右方必须给出注释以表明程序块结束。switch语句由于某种情况在一个case结束后必须进入另一个case语句时,必须加上注释。

6、其他需要注意的事项:应该避免在一行代码或表达式中使用注释;函数,变量,结构等的命名尽量遵循规范,使代码成为自注释的;注释应该是对代码的解释或对意图的说明,帮助理解代码。
二、排版

正确的排版方式有助于程序的理解,增加可读性。并且在编写代码的过程中,有助于梳理思路。

1、程序块必须采用缩进风格编写,最好是缩进4个空格。最好不用使用“tab”键,不同的编辑器对“tab”的解释方式不同,容易造成混乱。

2、相对独立的程序块之间、变量说明之后必须加空行。

3、较长的语句应该换行。尽量在低优先级的操作符出换行。换行要有必要缩进,并把操作符放在此行最前面。如果是函数的参数,则不允许将某一参数隔断,应该在两个参数之间换行,中间的逗号放在上一行的最后,

4、if、for、do、while、case、switch、default等语句自占一行,且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。括号(程序块的分界符)也独占一行,不缩进,其内语句才开始缩进。

5、多个短句不允许放在同一行。

6、在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如->),后不应加空格。

三、 标识符命名
1、标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。
说明:较短的单词可通过去掉“元音”形成缩写;较长的单词可取单词的头几个字母形成缩写;一些单词有大家公认的缩写。
示例:如下单词的缩写能够被大家基本认可。
temp      可缩写为  tmp  ;
flag      可缩写为  flg  ;
statistic 可缩写为  stat ;
increment 可缩写为  inc  ;
message   可缩写为  msg  ;

2、命名中若使用特殊约定或缩写,则要有注释说明。
说明:应该在源文件的开始之处,对文件中所使用的缩写或约定,特别是特殊的缩写,进行必要的注释说明。

3、自己特有的命名风格,要自始至终保持一致,不可来回变化。
说明:个人的命名风格,在符合所在项目组或产品组的命名规则的前提下,才可使用。(即命名规则中没有规定到的地方才可有个人命名风格)。

4、对于变量命名,禁止取单个字符(如i、j、k…),建议除了要有具体含义外,还能表明其变量类型、数据类型等,但i、j、k作局部循环变量是允许的。
说明:变量,尤其是局部变量,如果用单个字符表示,很容易敲错(如i写成j),而编译时又检查不出来,有可能为了这个小小的错误而花费大量的查错时间。
示例:下面所示的局部变量名的定义方法可以借鉴。
int liv_Width
其变量名解释如下:
l      局部变量(Local)  (其它:g    全局变量(Global)…)
i      数据类型(Interger)
v      变量(Variable)   (其它:c    常量(Const)…)
Width  变量含义
这样可以防止局部变量与全局变量重名。

5、命名规范必须与所使用的系统风格保持一致,并在同一项目中统一,比如采用UNIX的全小写加下划线的风格或大小写混排的方式,不要使用大小写与下划线混排的方式,用作特殊标识如标识成员变量或全局变量的m_和g_,其后加上大小写混排的方式是允许的。
示例: Add_User不允许,add_user、AddUser、m_AddUser允许。

6、:除非必要,不要用数字或较奇怪的字符来定义标识符。
示例:如下命名,使人产生疑惑。
#define _EXAMPLE_0_TEST_
#define _EXAMPLE_1_TEST_
void set_sls00( BYTE sls );

应改为有意义的单词命名
#define _EXAMPLE_UNIT_TEST_
#define _EXAMPLE_ASSERT_TEST_
void set_udt_msg_sls( BYTE sls );

7、在同一软件产品内,应规划好接口部分标识符(变量、结构、函数及常量)的命名,防止编译、链接时产生冲突。
说明:对接口部分的标识符应该有更严格限制,防止冲突。如可规定接口部分的变量与常量之前加上“模块”标识等。

8、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

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 );

9、除了编译开关/头文件等特殊应用,应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义

版权信息 放在包信息之前:
/**
*Copyright(c)2002SScompany Co.Ltd.
*Allrightreserved.
*/

类信息 放在类名之前:
/**
*<p>Title:描述这个类属于哪一系统哪一模块</p>
*<p>Description: 描述该类实现了什么功能,尽可能详尽</p>
*<p>Copyright:Copyright(c)2010</p>
*<p>Company:SScompany</p>
*@author你的大名
*@version目前项目的版本号,默认为1.0
*/
类信息的@version 信息由项目组决定,不过很少有项目组更改version信息。

方法信息 放在方法之前:
/**
*对方法功能的描述
*@param参数1
*@param参数2
*@return 返回类型
*@throws这个方法所抛出的异常
*/


代码块信息  放在需要注释的代码块之前:

/* 对代码块功能性的描述

But advocates for families of children with disabilities said the decision removed an important lever for settling disagreements with districts Chosen by the people at google’s android team the following 11 apps were recently featured on a blog company web service post at official android developers blog

标签:
本文连接地址: http://www.fresker.com/archives/264 (转载注明出处)

回复

目前暂无评论

Sorry, 评论已关闭.