javaDoc代码注释基本规范
代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。
原则:
1、注释形式统一
在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范。
2、注释内容准确简洁
内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。
注释条件:
基本注释(必须加)
(a) 类(接口)的注释
(b) 构造函数的注释
© 方法的注释
(d) 全局变量的注释
(e) 字段/属性的注释
备注:简单的代码做简单注释,注释内容不大于10个字即可,另外,POJO对象的getter、setter方法不需加注释。
特殊必加注释
(a) 典型算法必须有注释。
(b) 在代码不明晰处必须有注释。
© 在代码修改处加上修改标识的注释。
(d) 在循环和逻辑分支组成的代码中加注释。
(e) 为他人提供的接口必须加详细注释。
备注:此类注释格式暂无举例。具体的注释格式自行定义,要求注释内容准确简洁。
注释格式:
1、单行(single-line)注释://……
2、块(block)注释:/*……*/
3、文档注释:/**……*/
备注:对于不规范的注释注解,在idea中也会有黄色的warning或者波浪下划线的weak warning等的提醒出现。
javadoc 注释标签语法
在注释中正确的使用注解是有效提高工具利用率以及效率的事
比如idea工具中设置:
Editor>General> Code Completion > 勾选Show the documentation popup in 500
ms
然后鼠标悬停在方法或者类上,就会按照注释的内容将文档展现出来
一个正确示例
/**
* Returns the value to which the specified key is mapped,
* or {@code null} if this map contains no mapping for the key.
*
* <p>More formally, if this map contains a mapping from a key
* {@code k} to a value {@code v} such that
* {@code Objects.equals(key, k)},
* then this method returns {@code v}; otherwise
* it returns {@code null}. (There can be at most one such mapping.)
*
* <p>If this map permits null values, then a return value of
* {@code null} does not <i>necessarily</i> indicate that the map
* contains no mapping for the key; it's also possible that the map
* explicitly maps the key to {@code null}. The {@link #containsKey
* containsKey} operation may be used to distinguish these two cases.
*
* @param key the key whose associated value is to be returned
* @return the value to which the specified key is mapped, or
* {@code null} if this map contains no mapping for the key
* @throws ClassCastException if the key is of an inappropriate type for
* this map
* (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
* @throws NullPointerException if the specified key is null and this map
* does not permit null keys
* (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
*/
V get(Object key);
以上是我们常用的接口Map中的get方法 java.util.Map#get ;从上面我们可以看到几个最常用注解 @param,@return,@throws
主要标签 Tag Descriptions
@author 作者
对类的说明 标明开发该类模块的作者, 每个作者对应一个标签。
/**
* @author Axx
* @author Bxx
*/
{@code text} 当注释中需要写代码的时候
把代码显示成文本,而不是将文本解释为HTML标记或嵌套的Javadoc标签。比如<T,E>
这样的尖括号内容
@deprecated 弃用的
在被标记为@Deprecated的api上使用, 弃用文本的第一句应该告诉用户API何时弃用以及使用什么替换。随后的句子也可以解释为什么它被弃用。您应该包括一个{@link}标记(对于JavaDoc1.2或更高版本),该标记指向替换API。
{@docRoot}
文档的根目录,一般代替…/…/…/这样的存在
@exception class-name description
与@throws标记相同。请参见@throws类名描述。
{@inheritDoc}
为了表明一个方法是实现一个interface,我们可以使用{@inheritDoc}来标识,同时,该tag会把super type的注释复制下来。我们有可能改变接口的约定(不推荐这么做),这时,可以只注释改变的注释元素。
所有的注释继承都有拼接功能,如
* @return {@inheritDoc} a+b.
* @throws IOException {@inheritDoc} when file is missed.
返回值注释会继承父类的返回值注释,在加上新的注释。
异常注释会继承父类的异常注释,在加上新的注释。
{@link package.class#member label}
插入带有可见文本标签的内联链接,该标签指向引用类的指定包、类或成员名称的文档
此标记类似于@see标记。两个标记都需要相同的引用,并接受package.class#member和label的相同语法。
如果需要在标签内使用右大括号(}),则使用HTML实体表示法
{@linkplain package.class#member label}
行为与{@link}标记相同,只是链接标签以纯文本而不是代码字体显示。标签为纯文本时非常有用。例如,请参阅{@linkplain add()重写的方法}。显示为:参考重写的方法。
{@literal text}
显示文本,可以直接用 {@code text}
@param parameter-name description 参数
最常用的,标注API参数,以及参数的说明等等
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param <T> the type of the element
* @param <V> the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) {
}
@return
添加带有说明文本的返回部分。本文应描述返回类型和允许的值范围。此标记仅在方法的文档注释中有效。
@see reference
添加带有指向引用的链接或文本条目的SEE标签, 文档注释可以包含任意数量的@see标记,这些标记都分组在同一标题下。@see标记有三种变体。这种形式是最常见的。此标记在任何文档注释中都有效:概述、包、类、接口、构造函数、方法或字段。要在句子中插入指向包、类或成员的内联链接,请参见{@link}。
@serial field-description | include | exclude
在默认可序列化字段的文档注释中使用。如果在类可序列化之后向类添加了可序列化字段,则应在其主描述中添加一条语句,以标识添加该字段的版本。
@serialData data-description
使用“数据描述”值记录序列化表单中的数据类型和顺序。此数据包括writeObject方法写入的可选数据和Externalizable.writeExternal方法写入的所有数据(包括基类)。
@serialData标记可以在writeObject、readObject、writeExternal、readExternal、writeReplace和readResolve方法的文档注释中使用。
@serialField field-name field-type field-description
Documents an ObjectStreamField
component of the serialPersistentFields
member of a Serializable
class. Use one @serialField
tag for each ObjectStreamField
component.
@since since-text
一般jdk中用于标注自什么版本(since-text)开始,在实际开发过程中可以用此标签去标记版本,或者迭代或者其他可替代时间的信息
@throws class-name description
行为与@exception标记相同。有关如何为Javadoc工具编写文档注释,请参见@throws
@throws标记向生成的文档添加一个throws子标签,其中包含类名和描述文本。类名是该方法可能引发的异常的名称。此标记仅在方法或构造函数的文档注释中有效。如果未完全指定此类,则javadoc命令使用搜索顺序查找此类。对于相同或不同的异常,可以在指定的文档注释中使用多个@throws标记。
/**
* @throws IOException If an input or output
* exception occurred
*/
public void f() throws IOException {
// body
}
只有在重写方法中显式声明异常时,@throws文档才会从重写方法复制到子类。从接口方法复制到实现方法也是如此。您可以使用{@inheritDoc}标记强制@throws标记继承文档。
{@value package.class#field}
显示常量值
@version version-text
官方参考文档: