java代码注释基本规范 TODO未完待续

java代码注释基本规范

代码注释是架起程序设计者与程序阅读者之间的通信桥梁，最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。

原则：

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

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

一个正确示例

V get(Object key);

以上是我们常用的接口Map中的get方法 java.util.Map#get ；从上面我们可以看到几个最常用注解 @param，@return，@throws

主要标签 Tag Descriptions @author 作者

对类的说明 标明开发该类模块的作者， 每个作者对应一个标签。

{@code text} 当注释中需要写代码的时候

把代码显示成文本，而不是将文本解释为HTML标记或嵌套的Javadoc标签。比如 这样的尖括号内容

@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参数,以及参数的说明等等

 V convert(String string, Class 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标记。

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)