java注释规范

很多java初学者不善于书写注释或者根本不写注释，这样大大降低了代码的可读性。在团队开发的时候，不写注释是大忌，会大大降低开发效率。然而，注释的书写也有讲究，可不仅仅是//和/**/这么简单，下面我们来看一下注释的规范。

在为具体代码编写注释的同时，我们应该为下面的几种情况添加文档注释

• 包
• 公有类与接口
• 公有的和受保护的构造器及方法
• 公有的和受保护的成员变量

类注释以/*开始，以/结束，如下：

/**
这是一个类注释
*/
public class Dog
{

}

方法注释

每一个方法注释必须放在所描述的方法之前。除了通用标记之外，还可以使用下面的标记
@param变量描述
这个标记将对当前方法的"param" (参数)部分添加一个条目。这个描述可以占据多行并可以使用HTML标记。一个方法的所有@param 标记必须放在一起。
@return描述
这个标记将对当前方法添加"return" (返回) 部分。这个描述可以跨越多行，并可以使用HTML标记。
@throws类描述
这个标记将添加一一个注释， 用于表示这个方法有可能抛出异常。

域注释

只需要对公有成员变量（通常指静态常量）建立注释，如：

/**
这是COUNT
*/
public static final int COUNT = 1;

通用注释

下面的标记可以用在类文档的注释中。
@author 姓名
这个标记将产生一个” author" (作者) 条目。可以使用多个@author标记，每个author标记对应一个作者。
@version 文本
这个标记将产生个version (版本)条目，这里的文本可以是对当前版本的任何描述。

下面的标记可以用于所有的文档注释中。

@since 文本
这个标记将产生一个“ since" (始于)条目。这里的text可以是对引入特性的版本场述。例如，@since version 1.7.1。
@deprecated 文本
这个标记将对类、方法或变量添加一个不再使用的注释。文本中给出了取代的建议。例如，

@deprecated Use <code> setVisible(true) </code> instead

通过@see和@link标记，可以使用超级链接，链接到javadoc文档的相关部分或外部文档。