建议：为所有导出的API元素编写文档注释。

喜欢ヅ旅行 2024-02-18 21:34 26阅读 0赞

如果要想使一个API真正可用，就必须为其编写文档。传统意义上的API文档是手工生成的，所以保持文档与代码同步是一件很繁琐的事情。Java语言环境提供了一种被称为Javadoc的实用工具，从而使这项任务变得很容易。Javadoc林永特殊格式的文档注释，根据源代码自动产生API文档。

如果你对文档注释的规范还不太熟悉，应该去了解这些规范。虽然这些规范还没有正式成为Java程序设计语言的一部分，但他们已经构成了每个程序员都应该知道的事实API。这些规范的内容在Sun公司关于如何编写文档注释的网页上进行了说明。虽然这个网页在Java 1.4发行版本之后还没有进行更新，但他仍然是个很有价值的资源。Java 1.5发行版本中，为Javadoc新增了两个重要的Javadoc标签：\{@literal\}和\{@code\}。

为**了正确的编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。**如果类是可序列化的，也应该对他的序列化形式编写文档。如果没有文档注释，Javadoc所能够做的也就是重新生成该声明，作为受影响的API元素的唯一文档。使用没有文档注释的API是非常痛苦的，也很容易出错。为了编写出可维护的代码，还应该为那些没有被导出的类、接口、构造器、方法和域编写文档注释。

**方法的文档注释应该简洁的描述出他和客户端之间的约定。**除了专门为继承而设计的类中的方法之外，这个约定应该说明这个方法做了什么，而不是说明他是如何完成这项工作的。文档注释应该列举出这个方法的所有前提条件和后置条件，所谓前提条件是指为了使客户能够调用这个方法，而必须要满足的条件；所谓后置条件是指在调用成功完成之后，哪些条件必须要满足。一般情况下，前提条件是由@throws标签针对未受检的异常所隐含描述的；每个未受检的异常都对应一个前提违例。同样的，也可以在一些受影响的参数的@param标记中指定前提条件。

除了前提条件和后置条件之外，每个方法还应该在文档中描述他的副作用。所谓副作用是指系统状态中可以观察到的变化，他不是为了获得后置条件而明确要求的变化。

为了完整的描述方法的约定，方法的文档注释应该让每个参数都有一个@param标签，以及一个@return标签（除非这个方法返回类型为void），以及对于该方法抛出的每个异常，无论是受检的还是未受检的，都有一个@throws标签。按惯例，跟在@param标签或者@return标签后面的文字应该是一个名词短语，描述了这个参数或者返回值所表示的值。跟在@throws标签之后的文字应该包含单词“if”，紧接着是一个名词短语，他描述了这个异常将在什么样的条件下会被抛出。有时候，也会用算术表达式来代替名词短语。按惯例，@param、@return或者@throws标签后面的短语或者子句都不用句点来结束。

注意，这份文档注释中使用了HTML标签。Javadoc工具会把文档注释翻译成HTML，文档注释中包含的任意HTML元素都会出现在结果HTML文档中。有时候，程序员会把HTML表格嵌入到他们的文档注释中，但是这种做法并不多见。

还要注意，@throws子句的代码片段中到处使用了Javadoc的\{@code\}标签。他有两个作用：造成该代码片段以代码字体进行呈现，并限制HTML标记和嵌套的Javadoc标签在代码片段进行处理。后一种属性正是允许我们在代码片段中使用小于号（<）的东西，虽然他是一个HTML元字符。在Java 1.5发行版本之前，是通过使用HTML标签和HTML转义，将代码片段包含在文档注释中。**现在再也没有必要在文档注释中使用HTML <code>或者<tt>标签了：Javadoc\{@code\}标签更好，因为他避免了转义HTML元字符。**为了将多个代码示例包含在一个文档注释中，要使用包在HTML的<pre>标签里面的Javadoc\{@code\}标签。换句话说，是先在多行的代码示例前使用字符<pre>\{@code,然后在代码后面加上\}</pre>。

最后，要注意这个文档注释中用到了单词“this”。按惯例，当“this”被用在实例方法的文档注释中时，他应该始终是指方法调用所在的对象。

不要忘记，为了产生包含HTML元字符的文档，比如小于号（<）、大于号（>）以及“与”号（&），必须采取特殊的动作。让这些字符出现在文档中的最佳办法是用\{@literal\}标签将他们包围起来，这样就限制了HTML标记和嵌套的Javadoc标签的处理。除了他不以代码字体渲染文本之外，其余方面就像\{@code\}标签一样。

产生了这样的文档：“The triangle inequality is |x+y| < |x| + |y|.”\{@literal\}标签也可以只是包住小于号，而不是整个不等式，所产生的文档是一样的，但是在源代码中见到的文档注释的可读性就会更差。这说明了一条通则：文档注释在源代码和产生的文档中都应该是易于阅读的。如果无法让两者都易读，产生的文档的可读性要优先于源代码的可读性。

每个文档注释的第一句话成了该注释所属元素的概要描述。概要描述必须独立的描述目标元素的功能。为了避免混淆，同一个类或者接口中的两个成员或者构造器，不应该具有同样的概要描述。特别要注意重载的情形，在这种情况下，往往很自然的在描述中使用同样的第一句话（但在文档注释中这是不可接受的）。

注意所期待的概要描述中是否包括句点，因为句点会过早的终止这个描述。例如，一个以“A college degree, such as B.S., M.S., or Ph.D.”开头的文档注释，会产生这样的概要描述：“A college degree, such as B.S, M.S.”问题在于，概要描述在后面接着空格、跳格或者行终结符的第一个句点处（或者在第一个块标签处）结束。在这种情况下，缩写“M.S.”中的第二个句点就要接着用一个空格。最好的解决方法是，将讨厌的句点以及任何与\{@Literal\}关联的文本都包起来，因此在源代码中，句点后面就不再是空格了。

说概要描述是文档注释中的第一个句子，这似乎有点误导。规范指出，概要描述很少是个完整的句子。对于方法和构造器而言，概要描述应该是个完整的动词短语（包含任何对象），他描述了该方法所执行的动作。

对于类、接口和域，概要描述应该是一个名词短语，他描述了该类或者接口的实例，或者域本身所代表的事物。

Java 1.5发行版本中增加的三个特性在文档注释中需要特别小心：泛型、枚举和注解。**当为泛型或者方法编写文档时，确保要在文档中说明所有的类型参数。**

**当为枚举类型编写文档时，要确保在文档中说明常量，**以及类型，还有任何公有的方法。注意，如果文档注释很简短，可以将整个注释放在一行上。

**为注解类型编写文档时，要确保在文档中说明所有成员，以及类型本身。**带有名词短语的文档成员，就像是域一样。对于该类型的概要描述，要使用一个动词短语，说明当程序元素具有这种类型的注解时他表示什么意思。

从Java 1.5发行版本开始，包级私有的文档注释就应该放在一个称作package-info.java的文件中，而不是放在package.html中。除了包级私有的文档注释之外，package-info.java也可以（但并非必须）包含包声明和包注解。

类的导出API有两个特征经常被人忽视，即线程安全性和可序列化性。类是否是线程安全的，应该在文档中对他的线程安全级别进行说明，如果类是可序列化的，就应该在文档中说明他的序列化形式。

Javadoc具有“继承”方法注释的能力。如果API元素没有文档注释，Javadoc将会搜索最为适合的文档注释，接口的文档注释优先于超类的文档注释。也可以利用\{@inheritDoc\}标签从超类型中继承文档注释的部分内容。这意味着，不说别的，类还可以重用他所实现的接口的文档注释，而不需要拷贝这些注释。这项机制有可能减轻维护多个几乎相同的文档注释的负担，但他使用起来比较需要一些小技巧，并具有一些局限性。

为了降低文档注释中出错的可能性，一种简单的方法是通过一个HTML有效性检查器来运行由Javadoc产生的HTML文件。这样可以检测出HTML标签的许多不正确的用法，以及应该被转义的HTML元字符。Internet上有一些HTML有效性检查器可供下载，并且可以在线检验HTML。

对于文档注释有一点需要特别注意。虽然为所有导出的API元素提供文档注释是必要的，但是这样做并非永远就足够了。对于由多个相互关联的类组成的复杂API，通常有必要用一个外部文档来描述该API的总体结构，对文档注释进行补充。如果有这样的文档，相关的类或者包文档注释就应该包含一个对这个外部文档的链接。

简而言之，要为API编写文档，文档注释是最好、最有效的途径。对于所有可导的API元素来说，使用文档注释应该被看做是强制性的。要采用一致的风格来遵循标准的约定。记住，在文档注释内部出现任何HTML标签都是允许的，但是HTML元字符必须要经过转义。