Java开发规范总结

规范需要平时编码过程中注意,是一个慢慢养成的好习惯

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.<Strong>主要的类使用</Strong>如何使用该类, 包括环境要求,如是否线程安全,并发性要求, 以及使用约束
          4.<Strong>已知的BUG</Strong>
          5.描述类的修改历史:<Strong>修改人+日期+简单说明</Strong>
          6.@author作者、@version版本, @see参照,@since开始版本等信息如:

/** * This class provides default implementations for the JFC <code>Action</code> * interface. Standard behaviors like the get and set methods for * <code>Action</code> object properties (icon, text, and enabled) are defined * here. The developer need only subclass this abstract class and * define the <code>actionPerformed</code> method. * <p> * <strong>Warning:</strong> * 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. * * @version 1.41 2015/05/26 * @author xxxxx * @see Action */

为了使形成的文档可读性好,注释中经常带有缩进和格式控制。类描述放在类的类定义的紧前面,不能有任何的空行。

3.变量注释

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/5468ec9705543c77d7bd4965cbafea46.html