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