javaDoc代码注释基本规范(持续改进)

嘿嘿嘿嘿嘿~

已于 2022-03-02 15:45:28 修改

阅读量5.5k

点赞数

分类专栏： java 持续跟踪文章标签： java 代码规范

于 2021-11-10 20:04:54 首次发布

本文链接：https://blog.csdn.net/y965588107/article/details/121091834

版权

java 同时被 2 个专栏收录

15 篇文章 1 订阅

订阅专栏

持续跟踪

1 篇文章 0 订阅

订阅专栏

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 500ms

然后鼠标悬停在方法或者类上，就会按照注释的内容将文档展现出来

一个正确示例

/**
 * 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

官方参考文档：

How to Write Doc Comments for the Javadoc Tool (oracle.com)

javadoc (oracle.com)