规范需要平时编码过程中注意,是一个慢慢养成的好习惯
1.基本规则
1.注释应该使代码更加清晰易懂
2.注释要简单明了,只要提供能够明确理解程序所必要的信息就可以了。如果注释太复杂说明程序需要修改调整,使设计更加合理。
3.注释不仅描述程序做了什么, 还要描述为什么要这样做,以及约束
4.对于一般的getter、setter方法不用注释
5.注释不能嵌套
6.生成开发文档的需要用中文编写
2.三种注释方式说明
1.文档注释 /** */
可以对用多行,一般用来对类、接口、成员方法、成员变量、静态字段、静态方法、常量进行说明。Javadoc可以用它来产生代码的文档。为了可读性,可以有缩进和格式控制。
文档注释常采用一些标签进行文档的特定用途描述,用于帮助Javadoc产生文档,常用的有:
标签
Used for
目的
@author name
类/接口
描述代码的作者,每个作者对应一个这样的标签
@deprecated
类
成员方法
说明该段API已经被废除
@exception name description
或
@throws name description
成员方法
描述方法抛出的异常
每个异常一个对应一个这样的标签
@param name description
成员方法
描述成员方法中的参数用途和意义,一个参数对应一个这样的标签
@return description
成员方法
描述成员方法的返回值的意义
@since
类/接口
成员方法
描述该段API开始的时间
@see ClassName
类/接口
成员方法
成员变量
用于引用特定的类描述,一般ClassName用包括包名的全名
@see ClassName#memberfunction
类/接口
成员方法
成员变量
用于引用特定的类的成员方法的描述,一般ClassName用包括包名的全名
@version text
类/接口
版本
@inheritDoc
类/接口
成员方法
继承的文档
2.行注释 //
一次只能注释一行,一般用来简短的描述某一个局部变量,程序块的作用
3.块注释: /* */
在代码中禁止使用
4.类/接口注释
类/接口描述,一般比较详细。按照常用的说明顺序排列,主要包括
1.类的主要说明,以。或.结束
2.类设计的目标,完成什么样的功能
3.主要的类使用如何使用该类, 包括环境要求,如是否线程安全,并发性要求, 以及使用约束
4.已知的BUG
5.描述类的修改历史:修改人+日期+简单说明
6.@author作者、@version版本, @see参照,@since开始版本等信息如:
/*** This class provides default implementations for the JFC Action
* interface. Standard behaviors like the get and set methods for
* Action
object properties (icon, text, and enabled) are defined
* here. The developer need only subclass this abstract class and
* define the actionPerformed
method.
*
* Warning:
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is appropriate
* for short term storage or RMI between applications running the same
* version of Swing. A future release of Swing will provide support for
* long term persistence.
*
*@version1.41 2015/05/26
*@authorxxxxx
*@seeAction*/
为了使形成的文档可读性好,注释中经常带有缩进和格式控制。类描述放在类的类定义的紧前面,不能有任何的空行。
3.变量注释
1.成员变量、类静态变量采用文档注释,对成员变量的注释通常包括:
1)变量的意义
2)变量的合法值域
3)对并发访问的限制
如:
/*** Web.xml文件中configServlet参数的UIAPP.xml initparam*/
public final static String APP_CONFIG = "aaa.uiapp";
2.局部变量,如算法相关的变量采用块或行注释
public voidfunc() {int i; //用于循环计数
…………
}
3.参数变量注释一般用文档注释,并且用@param来说明为参数,一般包括
1) 参数的用途
2) 对参数值范围的要求
4.方法注释
描述函数的功能,对成员方法,静态方法一般采用文档描述,特别是公开的方法。注释可以很详细,为了可读性强也可包含格式控制,如下面说明含有缩进:
/*** Here is a method comment with some very special
* formatting that I want indent(1) to ignore.**/
方法注释一般包括:
1.方法的主要说明,以。或.结束
2.描述方法完成什么样的功能,方法的目标,用该方法的原因
3.描述方法的使用方法,包括使用的环境要求,如前置条件,后置条件和并发性要求
4.描述已知的bug
5.描述方法的修改历史:修改人+日期+简单说明 ()
6.@param c elements to be inserted into this list.(参数说明)
7.@return true if this list changed as a result of the call.(返回值说明)
8.@throws NullPointerException if the specified Collection is null.(异常说明)
9.@see如果重载方法必须参考父类的方法
10Eclips下采用Alt+Shift+J生成Javadoc说明方法的放回值((@return)
5.修改记录
1.在修改一个类前,必须先从SVN中update,之后再进行修改;
2.修改的地方必须加入注释,说明修改人,修改原因,修改内容,修改时间;