JAVA代码注释规范

JAVA代码注释规范

注释是代码必不可少的一部分，注释提高了代码的可读性；是架起程序设计这与阅读者之间的通信桥梁，最大限度的提高了团队开发合作效率，也提高了代码的维护效率。

注释原则

1、注释内容：
简洁明了，含义准确，语言严谨，防止注释多义性！

注释条件：

1、基本注释：（必须添加）

（a）：类（接口）的注释

1.   类（接口）注释
 /**

* 类的描述

* @author Administrator

* @Time 2012-11-2014:49:01

*

*/

public class Man extends Person{

  ……

}

（b）：构造函数的注释

2.   构造方法注释

例如:

public class Man extends Person {

  /**

   * 构造方法 的描述

   * @param name

   *       按钮的上显示的文字

   */

  public man(String name){

     ……

  }

}

（c）：方法的注释

3.   方法注释

例如

public class Man extends Person{

  /**

   * 为按钮添加颜色

   *@param color

         按钮的颜色

*@return

*@exception  (方法有异常的话加)

* @author Administrator

* @Time2012-11-20 15:02:29

   */

  public color(String color){

     ……

  }

}

（d）：全局变量的注释

4.   全局变量注释

例如：

public final class String

   implements java.io.Serializable, Comparable<String>,CharSequence

{

   /** The value is used for characterstorage. */

   private final char value[];

   /** The offset is the first index of thestorage that is used. */

   private final int offset;

   /** The count is the number of charactersin the String. */

   private final int count;

   /** Cache the hash code for the string */

private int hash; // Default to 0

……

}

（e）：字段/属性的注释

public class User {
    private String name;//账号
    private String password;//密码

    private int nums;//会员号

注：简单的代码做简单的注释，只是内容一般控制在10个字内；持久化对象或vo对象的getter、setter方法不需要注释！

2、特殊必须加注释：

(a) 典型算法必须有注释。

(b) 在代码不明晰处必须有注释。

© 在代码修改处加上修改标识的注释。

(d) 在循环和逻辑分支组成的代码中加注释。

(e) 为他人提供的接口必须加详细注释。
具体的注释格式自行定义

注释格式：

1、单行(single-line)注释：“//……”

2、块(block)注释：“/……/”

3、文档注释：“/**……*/”

4、javadoc 注释标签语法

标签	作用域	说明
@author	类	标明开发该类模块的作者
–	–	–
@version	类	标明该类模块的版本
–	–	–
@see	类，属性，方法	参考转向（相关主题）
–	–	–
@param	方法	对方法中某参数的说明
–	–	–
@return	方法	对方法返回值的说明
–	–	–
@exception	方法	方法抛出的异常类型
–	–	–
@throws	方法	方法抛出的异常类型说明
–	–	–
@deprecated	方法	说明不建议使用该方法