JAVA 注释介绍及使用

注释类型

1、单行注释

//一般是用于功能性注释

2、多行注释

/* */

3、文档注释

/** */其一般是用于说明性注释

常用标记

标签	描述	示例
@author	标识一个类的作者	@author
@deprecated	指名一个过期的类或成员	@deprecated description
{@docRoot}	指明当前文档根目录的路径	Directory Path
@exception	标志一个类抛出的异常	@exception exception-name explanation
{@inheritDoc}	从直接父类继承的注释	Inherits a comment from the immediate surperclass.
{@link}	插入一个到另一个主题的链接	{@link name text}
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体	Inserts an in-line link to another topic.
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@see	指定一个到另一个主题的链接	@see anchor
@serial	说明一个序列化属性	@serial description
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据	@serialData description
@serialField	说明一个ObjectStreamField组件	@serialField name type description
@since	标记当引入一个特定的变化时	@since release
@throws	和 @exception标签一样.	The @throws tag has the same meaning as the @exception tag.
{@value}	显示常量的值，该常量必须是static属性。	Displays the value of a constant, which must be a static field.
@version	指定类的版本	@version info

注释条件：

1、基本注释（必须加）

(a) 类（接口）的注释

(b) 构造函数的注释

© 方法的注释

(d) 全局变量的注释

(e) 字段/属性的注释

备注：简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。

2、特殊必加注释（必须加）

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

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

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

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

(e) 为他人提供的接口必须加详细注释。

备注：此类注释格式暂无举例。具体的注释格式自行定义，要求注释内容准确简洁。

参考举例：

1. 类（接口）注释

例如：

/**

* 类的描述

* @author Administrator

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

*

*/

publicclassTestextends Button {

  ……

}

2. 构造方法注释

例如:

publicclass Testextends Button {

  /**

   * 构造方法的描述

   * @param name

   *       按钮的上显示的文字

   */

  public Test(String name){

     ……

  }

}

3. 方法注释

例如：

publicclass Testextends Button {

  /**

   * 为按钮添加颜色

   *@param color

         按钮的颜色

*@return

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

* @author Administrator

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


   */

  publicvoidaddColor(String color){

     ……

  }

}

4. 全局变量注释

例如：

publicfinalclass String

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

{

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

   privatefinalcharvalue[];

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

   privatefinalintoffset;

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

   privatefinalintcount;

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

privateinthash;// Default to 0

……

}

5. 字段/属性注释

例如：

publicclass EmailBodyimplements Serializable{

   private Stringid;

   private StringsenderName;//发送人姓名

   private Stringtitle;//不能超过120个中文字符

   private Stringcontent;//邮件正文

   private Stringattach;//附件，如果有的话

   private StringtotalCount;//总发送人数

   private StringsuccessCount;//成功发送的人数

   private IntegerisDelete;//0不删除 1删除

   private DatecreateTime;//目前不支持定时所以创建后即刻发送

   privateSet<EmailList>EmailList;

……

}

其实规范是自己订的，只要团队中大家都统一遵守，统一规范，就会取得好的效果，希望对平时不加注释的朋友有点帮助。

摘抄自：
https://www.runoob.com/java/java-documentation.html
https://blog.csdn.net/drdongshiye/article/details/77160420