学会正确注释

  • 1.命名规范
  • 1.1Package 的命名
  • 1.2Class 的命名
  • 1.3Class 变量、方法的命名
  • 1.4Static Final 变量的命名
  • 1.5版权信息
  • 1.6类的注释
  • 2.注释规范
  • 2.1类注释
  • 2.2属性注释
  • 2.3方法注释
  • 2.4构造方法注释
  • 2.5方法内部注释


1.命名规范

1.1Package 的命名

Package 的名字应该都是由一个小写单词组成

1.2Class 的命名

Class 的名字必须由大写字母开头而其他字母都小写的单词组成

1.3Class 变量、方法的命名

变量、方法的名字必须用一个小写字母开头。后面的单词用大写字母开头。

1.4Static Final 变量的命名

Static Final 变量的名字应该都大写，并且指出完整含义。

1.5版权信息

版权信息必须在 java 文件的开头，比如:

/**

* Copyright ?0?3 2000 Shanghai XXX Co. Ltd.

* All right reserved.

*/

其他不需要出现在 javadoc 的信息也可以包含在这里。

1.6类的注释

类的注释，一般是用来解释类的。
/**
* A class representing a set of packet and byte counters
* It is observable to allow it to be watched, but only
* reports changes when the current set is complete
*/
接下来是类定义，包含了在不同的行的 extends 和 implements
public class CounterSet
extends Observable
implements Cloneable
Class Fields
接下来是类的成员变量:
/**
* Packet counters
*/
protected int[] packets;
public 的成员变量必须生成文档(JavaDoc)。proceted、private和 package 定义的成员变量如果名字含义明确的话，可以没有注释。

2.注释规范

2.1类注释

在每个类前面必须加上类注释，注释模板如下：
/**
• Copyright ©, 2006-2010, ChengDu Lovo info. Co., Ltd.
• FileName: Test.java
• 类的详细说明
• 
• @author 类创建者姓名
• @Date 创建日期
• @version 1.00
*/

2.2属性注释

在每个属性前面必须加上属性注释，注释模板如下：

/** 提示信息 */

private String strMsg = null;

2.3方法注释

在每个方法前面必须加上方法注释，注释模板如下：

/**

*类方法的详细使用说明

*@param 参数1 参数1的使用说明

*@return 返回结果的说明

*@throws 异常类型.错误代码 注明从此类方法中抛出异常的说明

*/

2.4构造方法注释

在每个构造方法前面必须加上注释，注释模板如下：

/**

  • 构造方法的详细使用说明

  • @param 参数1 参数1的使用说明
  • @throws 异常类型.错误代码 注明从此类方法中抛出异常的说明

*/

2.5方法内部注释

在方法内部使用单行或者多行注释，该注释根据实际情况添加。

如：//背景颜色

Color bgColor = Color.RED