代码形象——javadoc注释规范「建议收藏」

大家好，欢迎来到IT知识分享网。

javadoc注释规范

备注：本文结合了许多篇文章的内容加上自己的理解和经验，将很多零散的知识点，总结和统一整理与此。

你必须写注释而且按照项目规范来的写注释的理由

javadoc注释规范就是指文档注释，包括类、接口、方法、属性等的说明，在一个团队项目开发中，统一规范的注释很重要，对于自己以后的查看源码也极有帮助，如果没有相应的注释，那么给团队合作、自己查看源代码都会带来非常大的工作量。

而且需要了解的是，java doc编译生成的文档是html格式的，所以，我们就得遵循一些规范，不至于生成的文档杂乱无章。

要注意的是，生成的文档是 HTML 格式，而这些 HTML 格式的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入 ＜br＞，如果要分段，就应该在段前写入 ＜p＞。  

  因此，格式化文档，就是在文档注释中添加相应的 HTML 标识。  

  文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。如 /** 

* This is first line. ＜br＞ 

***** This is second line. ＜br＞ This is third line. */  

  编译输出后的 HTML 源码则是 This is first line. ＜br＞ This is second line. ＜br＞ This is third line.   

  前导的 * 号允许连续使用多个，其效果和使用一个 * 号一样，但多个 * 号前不能有其它字符分隔，否则分隔符及后面的 * 号都将作为文档的内容。

那么，哪些地方需要写注释？

基本注释

（1）类和接口

（2）构造方法

（3）普通方法（实体类对象的setter、getter方法不用注释）

（4）全局变量

（5）字段、属性

特殊注释

（1）典型算法

（2）在代码不明晰处

（3）在代码修改处加上修改标识注释

（4）在循环和逻辑分支组成的代码中注释

（5）为他人提供的接口必须详细注释

注释的格式、类型

单行注释：//……

块注释：/*……*/

文档注释：/**……*/

而javadoc，顾名思义，则是更多的是针对文档注释，本文也将大部分讲文档注释的java规范，那么，我们首先要了解，javadoc里的标记

下面为参考举例，可在eclipse或myeclipse中设置模板，下文有介绍（注释一定要紧跟者类、方法、属性）

1、类和接口的注释

/**
 * 
 * @ClassName Test_Singleton.java
 * @Description TODO
 * @Author 先
 * @Time 2017年3月25日 下午3:12:43
 *
 */
public class Test {
    //……
}

IT知识分享网

2、构造方法的注释

IT知识分享网/**
 * 
 * @Title: Test
 * @Description: TODO
 */
public Test(){
		
}

3、方法的注释

/**
 * 
 * @Title: test
 * @Description: TODO
 * @param para1
 * @param para2
 * @return String
 */
public String test(Integer para1,String para2){
		
	return para2;
}

4、属性、字段、全局变量的注释

IT知识分享网/**
 * (说明内容)
 */
private String name;
/**
 * (说明内容)
 */
private final Integer id;

一些标记的相关使用说明

1、@see

@see 的句法有三种： 

@see 类名  

@see #方法名或属性名

@see 类名#方法名或属性名

/**  
 * @see  java.lang.String 
 * @see  #str 
 * @see  #str() 
 * @see  #main(String[]) 
 * @see  java.lang.Object#toString() 
 */  

public classTestJavaDoc  {   

private Stringstr; 

public voidstr(){   }

public staticvoid main(String[] args){   }

}

生成的文档的相关部分如下图

2、@author、@version

这两个标记分别用于指明类的作者和版本。缺省情况下 javadoc 将其忽略，但命令行开关 -author 和 -version 可以修改这个功能，使其包含的信息被输出。

这两个标记的句法如下：   

@author 作者名  

@version 版本号   

其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效，生成的文档中只会显示第一次使用 @version 指明的版本号。如下例

/**  
 * @author Fancy
 * @author Bird
 * @versionVersion 1.00
 * @versionVersion 2.00
 */ 

public classTestJavaDoc {}

生成文档的相关部分如图

3.  @param、@return 和 @exception

这三个标记都是只用于方法的。@param 描述方法的参数，@return描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下： 

@param 参数名 参数说明

@return 返回值说明

@exception 异常类名 说明 

每一个 @param 只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用 @param 来描述。 

一个方法中只能用一个 @return，如果文档说明中列了多个@return，则 javadoc 编译时会发出警告，且只有第一个 @return 在生成的文档中有效。

方法可能抛出的异常应当用@exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 @exception。每个 @exception 后面应有简述的异常类名，说明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的 import 语句确定是写出类名还是类全名。示例如下：

public class TestJavaDoc {  

/** 
 * @param n a switch 
 * @param b excrescent parameter 
 * @return true or false 
 * @return excrescent return 
 * @exception java.lang.Exception throw when switch is 1
 * @exception NullPointerException throw when parameter n is null 
 */ 

public boolean fun(Integer n) throws Exception { 
    switch (n.intValue()) { 
        case 0:  break;   
        case 1: throw new Exception("Test Only"); 
        default:  return false; 
      } 
      return true; 
   }
}

使用 javadoc 编译生成的文档相关部分如下图：

那么，我们该怎么在eclipse或myeclipse中设置这些标记模板呢？

设置注释模板的入口： Window->Preference->Java->Code Style->Code Template

下面是每个comment的设置模板，个人也可以自定义，但是团队开发的话，就需要统一遵循一个

1、文件(Files)注释标签：

2、类型(Types)注释标签（类的注释）：

3、字段(Fields)注释标签：

4、构造方法（constructor）标签：

5、方法( Methods)标签：

6、覆盖方法(Overriding Methods)标签：

7、代表方法(Delegate Methods)标签：

8、getter方法标签：

9、setter方法标签：

另外附上维基百科的java doc规范链接https://en.wikipedia.org/wiki/Javadoc

希望对读者有帮助！转载请注明出处！