开发注释规范

 

为什么要有注释

 

企业级软件生命周期的80%用于维护，对代码的可读性和可维护性要求非常高，性能反而被放到其次；我们在编写程序的时候必须重视代码质量。

 

软件开发是一种高级脑力劳动，精妙的算法之后往往伴随着难以理解的代码，对于不经常维护的代码，往往连开发者本人也忘记编写的初衷。

 

SScompany的软件开发基于螺旋式软件开发模型，我们的Test系统在开发过程中不断因为不同客户的不同需求而做出相应的调整，不同项目组间同一功能模块的代码差异较大，即使同一项目组在不同时间段的代码也有可能完全不同，因此在开发更改过程中，需要编写注释来记录我们所做的每一件事情，以便以后的维护者可以更容易的了解代码编写的原因，过程。

 

诗言志，代码看人。要知道一个程序员的职业素养不用看薪金、资历、职位，只要去看他的代码便可知道，优雅的代码风格背后是高超技巧与丰富阅历的结合。好的代码使人钦佩，坏的代码使人鄙视；好的代码使人仰慕，坏的代码使人厌恶。出于经验和阅历的欠缺，我们可能无法写出大师级的优雅代码，但我们可以像大师们一样对代码详细注释。

 

注释概述

对大道的追求是人类不灭的理想，任何理论最终都是在解释这样的问题：我是谁？我从哪里来？我要到哪里去？ 同样，编写注释的目的有三： 描述程序的目的、解释程序的功能、提示程序的细节。

 

描述程序目的的部分要做到“详”、“尽”即又多又全，因为代码阅读者大部分时间是用来理解这段程序是怎么来地，（然后再了解这段程序是怎么没地）。根本目的在于告诉阅读者为什么会有着段程序这部分注释通常放在文件开头。

 

解释程序功能的部分要做到“精”、“准”即没有废话，一眼就能知道程序是做什么的，代码阅读者根据这些注释知道应该对程序作什么样的调整。这部分注释通常用来放在方法开头。

 

提示程序细节的部分需要编写者随机应变灵活控制，根据程序细节的不同或多或少或细或粗。其最终目的是让阅读者知道为什么程序要写成这样，这部分注释可能出现在代码的任何位置。

 

以下是一些通用注释规则:

 

1、除非必要，不允许修改任何描述性注释；除非确实对方法做出过修改，不允许修改任何解释性注释；根据实际修改情况修改提示性注释。

 

2、如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。

 

3、描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。

 

4、除HTML和不重要的Javascript外任何对文件（类）的注释必须加上SScompany版权所有标志，此举对我们Test系统的版权非常重要。

/**

  * Copyright (c) 2007 SScompany   Co. Ltd.

  * All right reserved.

  */

5、每行注释（连同代码）不要超过120个字(1024×768)，最好不要超过80字(800× 600) 。

 

6、任何注释必须遵循中文语法(英文注释必须遵循英文语法)，不能有错别字，正确使用标点符号。

 

7、当一段代码被更改，相应的注释也应改被更改。

 

下面将说明java，JSP，javascript的注释应如何编写

 

Java 程序注释编写

Java 编程语言有三种注释：

/**

  * java 风格的注释，可以生成 javadoc

  *

  */

 

/*

 * C 风格的注释

 */

 

// C++ 风格的注释

 

对于java风格和c风格的注释都必须保证‘*’对齐，注释写在‘*’加一个空格符之后。

C++风格的注释通常用于提示性注释，注释写在第二个‘/’加一个空格符之后。

关于JavaDoc的部分略去不表，我们直接谈谈我们SScompany的程序注释。

 

版权信息

放在包信息之前：

/**

  * Copyright (c) 2002 SScompany   Co. Ltd.

  * All right reserved.

  */

 

类信息

放在类名之前：

/**

  * <p> Title: 描述这个类属于哪一系统哪一模块 </p>

  * <p> Description: 描述该类实现了什么功能，尽可能详尽 </p>

  * <p> Copyright: Copyright (c) 2007 </p>

  * <p> Company: SScompany </p>

  * @author 你的大名

  * @version 目前项目的版本号，默认为 1.0

  */

类信息的@version 信息由项目组决定，不过很少有项目组更改version信息。

方法信息

放在方法之前：

/**

  * 对方法功能的描述

  * @param 参数 1

  * @param 参数 2

  * @return 返回类型

  * @throws 这个方法所抛出的异常

  */

 

代码块信息

放在需要注释的代码块之前：

/* 对代码块功能性的描述——单行注释。 */

/*

 * 当描述超过 120 字符时的代码块注释——多行注释。

 */

 

细节提示信息

细节提示信息的使用较为灵活：

// 这种类型的注释既可以放在某一行代码之后，也可放在几行代码之间。

// 循环 , 判断从 LdSet 取到的地址信息与保单中的地址信息是否相等。

for ( int i = 1; i <= tLdSet.size(); i++) {   // 遍历 tLdSet

    // 如果二者相等，则返回 true

    if (tLdSet.get(i).getPostalAddress() == cLontema

            .getAddress()) {                      

        return true ;

    } // end if

} // end for

 

失效代码：

当一段代码不再有效，但这段代码对于阅读者理解程序有重大意义，可以将其注释掉：

失效代码必须在代码块首尾加上批注

// [ 操作者 ] 年月日 代码失效原因 START

// [ 操作者 ] 年月日 代码失效原因 END

举例如下：

// [WULigang] 20071019 由于 CCtm 改用其它设置方式，这段代码不再有效 START

// contLdssEma.setOperator(tGlobal.Operator);

// contLdssEma.setMakeDate(CubEun.getCurrentDate());

// contLdssEma.setMakeTime(CubEun.getCurrentTime());

// contLdssEma.setModifyDate(CubEun.getCurrentDate());

// contLdssEma.setModifyTime(CubEun.getCurrentTime());

// [WULigang] 20071019 由于 CCtm 改用其它设置方式，这段代码不再有效 END

 

以下几点需要注意：

不可滥用，在程序中的任何一行代码和注释都必须是有意义的，对程序没有意义的任何语句和注释都必须摒弃。

/**

  * 这个类为赞美太阳而创建。

  */

/*

 * 这段代码非常帅，到底是做什么的呢？

 */

// 老吴老吴我爱你，就像老鼠爱大米。

这样的注释除了证明编写它的人智商不到100，没有任何用处。

 

没有价值的代码不应存在，当一段代码被废弃，将这段代码删除而不是仅仅注释掉它，只有在这段代码有可能被重新起用或者对本程序有重要意义的情况下，才能将它设置为无效代码。

 

标点符号，当一个行注释是一个完整的陈述句，用句号结束他；是个疑问句，用问号结束他，是一句英文，用英文标点结束他，是一句中文，用中文标点结束他。

 

“注释是让人更容易理解而不是更容易疑惑的存在” 前面这句话让人很难懂吗？，所以别在注释中用太复杂的语法。

 

不要在不合适的地方注释，例如不要在分行的字符串间加上注释

String testString = " 塞下秋来风景异，衡阳雁去无留意。 "

+ " 四面边声连角起，千嶂里，长烟落日孤城闭。 " // 上阕写景，塞下秋来，长烟落日

+ " 浊酒一杯家万里，燕然未勒归无计。 "

+ " 羌管悠悠霜满地，人不寐，将军白发征夫泪。 " ; // 下阕抒情，将军白发，征人难寐

一旦这个字符串需要改写或者合并成一行，中间的注释该何去何从？

 

所有用 /** …… */包围的注释内容都会出现在Javadoc中，所以不要在里面写你不想让API阅读者知道的信息。

JSP中的注释

JSP中最好使用

// 这种注释优于 /**/ 因为 MyEclips 编辑器可以将这种注释内容显示为绿色，易于与代码区分

而不是

/* 这种注释尽量不要用，因为 MyEclips 将里面的内容显示为黑色，不易与代码区分开来 */

描述性注释

<%

// 程序名称：通常是该 JSP 文件名

// 程序功能：该 JSP 功能描述

// 创建日期： 2002-06-19 11:10:36 （越精确越好）

// 创建人   ： CrtHtml 程序创建

// 更新记录：   更新人     更新日期       更新原因 / 内容

//             人名          日期            原因

// 例如：      niuzj 2006-08-23 YDtm 需要在录入受益人信息时增加一个 “ 性别 ” 字段

%>

幸福的JSP通常用于前台显示和数据提交，由于功能相对简单，我们不提倡在JSP中加入太多java风格的注释。

 

Javascript的注释

我们Test系统大部分javascript的注释写的较为凌乱，终其原因，大部分人都是以java软件工程师的身份进入公司，因此对javascript不够重视，实际上javascript是一种解释执行的语言，我们页面所运行的javascript实际上是每次客户端请求时从后台服务器发送过去的，因此javascript体积越小页面传输速度越快。

幸福项目组要求，新建立的.js文件在程序能够被理解的时候尽量不要在里面添加注释。

 

描述性注释示例，如果创建一份通用的js文件这部分信息是不可少的：

/*************************************************************************

 * <p>Title: Test 1.0</p>

 * <p>Description: SScompanyTest 管理系统 </p>

 * <p>Copyright: Copyright (c) 2005 SScompany, Co.Ltd. All Rights Reserved</p>

 * <p>Company: SScompany </p>

 * <p>WebSite: http://www.SScompany.com.cn</p>

 *

 * @author   : SScompany

 * @version : 1.00

 * @date     : 2006-11-08

 * @direction: Test 系统多行显示 / 输入表格

 * @comment : XinYQ formatted on 2006-11-08

 **************************************************************************/

但如果仅仅是创建一份用于某个单独页面逻辑的js文件，还是不要增加太多注释了，会影响速度的。

解释性注释

用于对js的function进行注释

/*****************************************************

 *  保存集体投保单的提交 （ function 的功能描述）

 *  参数   ：  ( 行参，由于 javascript 的 function 行参是没有类型标志的，最好在此告知参数类型 )

 *  返回值：   （返回信息，注意冒号与参数列表对齐，并描述返回值类型）

 *****************************************************

 */

提示性注释

除较为复杂的算法外，本文档不建议在Javascript文件大量编写提示性注释，此外，也不建议将业务逻辑放在javascript中，因为除了效率的考虑之外，javascript的安全性也值得怀疑。

提示性注释举例：

this .formName = formName || "fm" ; // 表单名称

this .name = name || "" ; // 实例名称

this .count = 0; // 行输入对象的行数

this .add = 1; // 是否可以允许增加，删除 1 表示可以， 0 表示不可以

this .select = 0; // 是否可以选择， 1 表示可以， 0 表示不可以

this .title = 1; // 是否现实 title 1 表示显示， 0 表示不显示

 

javascript注释可以参看common包中公司前辈们的大作，有些程序至今无人能改。考虑到 Test系统的总销售额，用一字千金来形容这些代码也不为过。

 

HTML的注释

HTML中主要是解释性注释，便于阅读者知道某一个TABLE或者DIV上应该输入什么样的 字段。

CCtm项目组的HTML中有两种主要注释方法

HTML风格的注释方法，可用于所有HTML和JSP文件

<!-- HTML 注释，会被发送到客户端，考虑到安全性，不推荐使用 -->

JSP 的注释方法同样可以注释HTML模块功能，只能用于JSP文件

<%-- JSP 引擎会自动忽略的注释，不会被发送到客户端，推荐使用 --%>

鸣谢

hjj    为CCtm项目组提供的培训。

lx      为CCtm项目组提供的注释规范。