编程规范——Java注释样式规范与模板

作为一个程序员，好的编程习惯是走向卓越的必要条件，好的注释，可以极大的增强代码的可读性，同时能让代码优雅美观，很多开源软件的代码风格均可借鉴。

另外，java注释，可生成对应的doc文件，养成好的注释习惯，就能够生成规范的开发文档！

1 类（接口）注释

/**
* 类的描述
* @author Administrator
* @Time 2012-11-2014:49:01
*
*/
public classTest extends Button {
  ……
}

2 构造方法注释

public class Test extends Button {
  /**
   * 构造方法 的描述
   * @param name
   *       按钮的上显示的文字
   */
  public Test(String name){
     ……
  }
}

3 方法的注释

public class Test extends Button {
  /**
   * 为按钮添加颜色
   *@param color
         按钮的颜色
   *@return
   *@exception  (方法有异常的话加)
   *@author Administrator
   *@Time2012-11-20 15:02:29
   */
  public voidaddColor(String color){
     ……
  }
}

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
   ……
}

5 字段/属性注释

public class EmailBody implements Serializable{
   private String id;
   private String senderName;//发送人姓名
   private String title;//不能超过120个中文字符
   private String content;//邮件正文
   private String attach;//附件，如果有的话
   private String totalCount;//总发送人数
   private String successCount;//成功发送的人数
   private Integer isDelete;//0不删除 1删除
   private Date createTime;//目前不支持定时 所以创建后即刻发送
   privateSet EmailList;
   ……
}

6 类描述信息

/**
* 这是一个测试类，用于说明注释的使用样式.
* 培养好的编程习惯！
*/
public class Test{
... ...
}

特别注意： javadoc通过英文状态的句号’.’来断句，这里需要注意对整体风格的影响！

7 @value
用于在文档中生成被标记的常量字段的值！

/**
* 默认的命名空间，其值为{@value}
*/
public static final String DEFAULT_NS = "XX__NS";

备注：也可以在其它地方通过如下形式引用

 {@value #DEFAULT_NS }

8 pre 标签
就是 HTML 的pre标签，用于显示“原始样子”，在Javadoc中非常有用，对于显示效果有影响！