Javadoc 最佳实践

列表在 Javadoc 中也很常用，比如用来表示一组选项、一些问题等等。推荐的做法是用一个 

/**
 * First paragraph.
 * 

 * 
the first item
 * 
the second item
 * 
the third item
 * 

 * Second paragraph.
 */
public ...

首句很重要

Javadoc 的首句（用英文句号结束）也被作为这个 Javadoc 的摘要，在折叠的时候只会显示这一句。因此首句必须是个总结性的描述，它最好简洁有力，不能太长。

虽然没有强制要求，我们建议首句自成一个段落，这让代码看起来更清晰。

对于英文注释，推荐使用第三人称来描述，比如 “Gets the foo”、“Sets the bar”、“Consumes the baz”。避免使用第二人称，比如 “Get the foo”。

用 “this” 指代类的对象

当你想描述这个类的一个实例（对象）的时候，用 “this” 来指代它，比如 “Returns a copy of this foo with the bar value updated”

别写太长的句子

尽量让一句话能容纳在一行中，一般来说一行有 80 到 120 个字符。

新的句子就另起一行，这会让代码可读性更好，也会让以后改写 Javadoc 容易很多。

/**
 * This is the first paragraph, on one line.
 * 

 * This is the first sentence of the second paragraph, on one line.
 * This is the second sentence of the second paragraph, on one line.
 * This is the third sentence of the second paragraph which is a bit longer so has been
 * split onto a second line, as that makes sense.
 * This is the fourth sentence, which starts a new line, even though there is space above.
 */
public ...

正确使用 @link 和 @code

很多地方的描述需要涉及到其他类或方法，这时最好用 @link 和 @code。

@link 会最终变成一个超链接，它有以下几种形式：

/**
 * First paragraph.
 * 

 * Link to a class named 'Foo': {@link Foo}.
 * Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}.
 * Link to a method 'baz' on this class: {@link #baz}.
 * Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
 * Link to a method handling method overload {@link Foo#bar(String,int)}.
 */
public ...

@code 用来标记一小段等宽字体，也可以用来标记某个类或方法，但不会生成超链接。

建议在第一次提到某个类或方法的时候用 @link，此后直接用 @code 即可。

不要在首句中使用 @link

之前提到，Javadoc 的首句也被用作概要，首句中的超链接会让读者感到混乱。如果一定要在第一句话中引用其它类或方法，始终用 @code 而不是 @link，第二句开始再用 @link。

null、true、false 不必用 @code 标记

null、true、false 这些词在 Javadoc 中太常用了，如果每次都加上 @code，无论是对读者还是作者都是个负担。

使用 @param、@return 和 @throws

几乎所有方法都会输入几个参数、输出一个结果，@param 和 @return 就是用来描述这些输入输出参数的，@throws 用于描述方法抛出的异常。

如果有多个输入参数，@param 的顺序也要和参数一致。@return 应当始终放在 @param 之后，然后才是 @throws。

为范型参数加上 @param

如果一个类或方法有范型参数（例如 ），这些参数也应当被文档化，推荐的做法是给  也加上一个 @param 说明。

在 @param 之前空一行

始终在 Javadoc 的内容和 @param、@return 之间留个空行，这让代码的可读性更佳。

用短语来描述 @param 和 @return

@param 和 @return 后面跟的的描述是个短语，而非完整的句子，因此它得用小写字母开头（经常是 the），结尾也不需要用句号。

用 if-句来描述 @throws

@throws 通常跟着一个 “if” 句子来描述抛异常的情形，比如 “@throws IllegalArgumentException if the file could not be found”。

@param 的参数名之后空两格

在源代码中阅读 Javadoc 的时候，如果参数名后面只有一个空格，读起来会有点困难，两个空格就好很多。另外，避免把参数按列对齐，否则参数改名、增减参数的时候会很麻烦。

/**
 * Javadoc text.
 * 
 * @param foo  the foo parameter
 * @param bar  the bar parameter
 * @return the baz content
 */
public String process(String foo, String bar) {...}

写明各参数和返回值的 null 行为

一个方法是否接受 null、会不会返回 null 对于其他开发者是十分重要的信息。除非是原始类型，@param 和 @return 都应该注明它是否接受或返回 null。以下标准若适用请务必遵循：

• “not null” 表明不接受 null，若输入 null 可能导致异常，例如 NullPointerException
• “may be null” 表明可以传入 null 参数
• “null treated as xxx” 表明 null 值等价于某个值
• “null returns xxx” 表明如果输入 null 则一定会返回某个值

定义清楚这些之后，不要再为 NullPointerException 写 @throws。

/**
 * Javadoc text.
 * 
 * @param foo  the foo parameter, not null
 * @param bar  the bar parameter, null returns null
 * @return the baz content, null if not processed
 */
public String process(String foo, String bar) {...}

有人可能想在某个地方（像是类或包的 Javadoc）集中定义 null 相关行为，但我们不建议你这么做，因为这对别人并没有帮助。方法上的 Javadoc 很容易就能看到，而类或包层级的 Javadoc 要去翻一遍才能找到。

其他简单的约束条件也建议写到 Javadoc 里，比如 “not empty, not null”。原始类型也可以加上边界约束，比如 “from 1 to 5” 或 “not negative”

给 Specification 加上 implementation notes

如果某个接口允许第三方来实现，而你为这个接口写了个正式的规格说明（specification），这时候考虑加个 “implementation notes” 章节。这通常出现在类的 Javadoc 上，用于描述一些不太好写在特定方法上的东西，或者一些其他人不感兴趣的东西。参考这个例子。

不要用 @author

@author 用来标记类的作者，这个功能已经过时了，不要用。版本控制系统（例如 git）会记住作者的。

例子

这个 ThreeTen 项目里有一些更完整的例子

总结

希望这些建议能帮你写出更好的 Javadoc。当然，这只是一份建议，你也可以选择其他标准来参考。