采用 Javadoc 形式的集成文档有利有弊(转)

Java 语言按照 Javadoc 注释约定采用了一种集成的方法来进行 api 文档编制。Javadoc 工具可以帮助生成好的 API 文档，然而大多数 Java API 文档却很糟糕。因为它是源代码的一部分，所以 API 的文档编制职责最终还是落到了工程师身上。在本文中，Brian 对 Java 文档编制实践的当前状态进行了严厉的批评，同时提供了一些关于如何编写更有用的 Javadoc 的准则。
对于大多数 Java 类库来说，Javadoc 是唯一的文档。而且，除了商业软件组件之外，许多 Java 类不会用到 Javadoc。虽然 Javadoc 作为 API 参考工具很出色，但对于了解类库是如何组织的和应该如何使用它来说，它却是一种十分差劲的方法。并且即便用了 Javadoc，它通常只包含有关方法完成了什么的最基本信息，而忽略了诸如错误处理、参数及返回值的作用域和范围、线程安全、锁定行为、前置条件、后置条件、不变条件或副作用之类的重要特性。

向 Javadoc 学习
对于包括大多数开放源码包和大多数内部开发的组件在内的许多 Java 工具而言，实际情况是：包括 Javadoc 在内，几乎所有类库或组件都不具有有效的文档。这就意味着开发人员要从 Javadoc 学习使用工具，而且我们应该考虑根据这一现实组织我们的 Javadoc。我经常开玩笑说：现在，Java 程序员需要具备的最重要的技能之一是熟练地使用 Google 和 Javadoc 来对那些文档编制得十分糟糕的 API 进行“逆向工程”。这可能是真的，但却并不十分好笑。

大多数 Java 包都有某种“根”对象，它是在得到该工具内的任何其它对象之前，必须创建的第一个对象。在 JNDI 中，该根对象是 Context，而在 JMS 和 JDBC 中，它是 Connection。如果有人告诉您 JDBC 中的基础对象是 Connection，以及如何获得这一对象，那么接着您很可能会从 Javadoc 中通过仔细察看 Javadoc 中可用的方法列表找到如何创建并执行 Statement，以及如何迭代生成的 ResultSet。但您如何知道获得 Connection 是您的第一步呢？Javadoc 在包内按照字母顺序组织类，在类中按照字母顺序组织方法。遗憾的是，Javadoc 中没有神奇的“从这里开始（Start Here）”记号把读者带到浏览 API 的逻辑开始位置。

包描述
最接近“从这里开始”记号的是包描述，但它却很少得到有效的使用。如果将文件 package.html 与源代码一起放在一个包中，那么标准的 doclet 会将已生成的 package-summary.html 文件中的内容连同类列表一起放在该包内。遗憾的是，生成我们都很熟悉的 HTML 文档的标准 doclet 却无法使包描述易于找到。如果您单击左上窗格中的某个包，那么这会在左下窗格中产生方法列表，但并不会在主窗格中产生包的摘要 ? 必须单击左下窗格中的包名称来查看摘要。但不要紧，毕竟大多数包并没有包描述。

包文档是一个放置“从这里开始”文档的极好的地方，这一文档用来概述包做什么、主要摘要是什么以及从何处开始浏览包的 Javadoc。

类文档
除包文档之外，特定于类的文档对于帮助用户彻底了解新工具也能起到重要的作用。类文档当然应该包括此特定类做什么的描述，但还应该描述该类与包中的其它类如何关联，特别是要标识任何与该类相关的工厂类。例如，JDBC 中的 Statement 类文档应该说明：Statement 是通过 Connection 类的 createStatement() 方法获得的。这样，如果一个新用户偶然进入 Statement 页面，那么他会发现首先他需要获得 Connection。对每个类都应用这一约定的包会迅速为用户指出根对象，用户因而能够得心应手。

因为 Javadoc 是围绕对特定类进行文档编制而设计的，因此在 Javadoc 中通常没有明显的位置来放置演示几个相关类一起使用的示例代码。但由于一味地侧重于特定类或方法的文档编制，我们失去了讨论如何组合包中内容的机会。如果对于根对象，在包文档或类文档中有一个演示一些基本用法的简单代码示例，则对于许多用户来说，将是非常有用的。例如，Connection 类文档可以有一个简单示例，该示例获取连接、创建预编译语句、执行该语句并迭代结果集。从技术上说，这可能不属于 Connection 页面，因为它还描述了包中的其它类。然而，尤其是当结合了上面那种引用当前类所依赖的类的技术时，用户才能非常迅速地找到获取简单的实用示例的途径，不管类的组织方式如何。

糟糕的文档 == 糟糕的代码
对于大多数 Java 类库来说，除了那些作为打包组件出售的商业产品之外，要么没有 Javadoc，要么非常糟糕。由于存在的事实是对于大多数包来说，Javadoc 是我们拥有的唯一文档，这基本上意味着使我们自己陷入了这样的困境：除了作者之外，其他人没法使用我们的大部分代码 ? 如果不付出重大的“考古”一样的努力，至少会这样。

由于文档现在是代码的一部分，因此我认为是软件工程社区形成一个共识的时候了，这就是，即使代码很出色，如果文档很糟糕，也应该被认为是差劲的代码，因为不能有效地重用。单元测试不久前还声誉不佳，只是到了最近它才受到了许多工程师的青睐，就和它一样，为了改善我们生产的软件的可靠性和可重用性，API 文档也必须成为开发过程的一个集成部分。

编写 Javadoc 就是某种形式的代码检查
编写合理的 Javadoc 也会产生副作用，它迫使我们进行某种形式的代码检查，来研究类的体系结构和它们之间的关系。如果单个包、类或方法很难编制文档，那么或许可以尝试同时对多个包、类或方法进行文档编制，这应该是个提示，即可能它需要重新设计。

文档的自我检查方面使得某些方面更加重要，即在开发过程中尽早编写 Javadoc，然后随着代码的不断开发，定期对其进行检查，而不是仅仅等待代码完成再编写文档（如果有剩余时间的话）。后一种策略十分常见，它将编写文档拖到项目最后，而那时时间安排十分紧张，开发人员的压力也很大。结果再常见不过了，就是图 1 所示的那种一文不值的文档，它只提供了“文档假象”。用户真正需要的是了解该类的工作原理，而该文档却没有提供任何这样的信息。

清单 1. 典型的一文不值的 Javadoc

public class CommandHistory {


public static CommandHistory getCommandHistory(String user) {
. . .
}
}



那么好的文档包括哪些内容呢？
上面描述的组织技术（在类描述中引用相关类或工厂类，也包括了包概述和代码样本）是形成优秀文档的好开端。它有助于新用户使用 Javadoc 了解新工具。

但体系结构的概述只完成了任务的一半。另一半则是详细地解释方法做什么和不做什么、在什么条件下运行以及它们如何处理错误条件。大多数 Javadoc 都没有完全提供所需的信息，即便是那些充分描述了方法在期望情况下的行为的 Javadoc 也是如此，这些缺少的信息包括：

方法如何处理错误条件或不合要求的输入
如何将错误条件传回给调用者
可能会抛出哪个特定异常的子类
哪些值对于输入是有效的
类不变条件、方法前置条件或方法后置条件
副作用
在方法之间是否有重要联接
类如何处理多个线程同时访问一个实例的情况。
Javadoc 约定提供了 @param 标记，它让我们除了能够对参数的名称和类型编制文档之外，还可以对其意义编制文档。然而，并不是所有的方法都能很好地接受参数的任何值。例如，虽然可以合法地向任何获取对象参数的方法传递空值（null）而不违反类型检查规则，但并不是所有的方法都能在传入空值时正常工作。Javadoc 应该显式地描述有效的参数范围，如果它希望某个参数非 null，那么它应该这样描述，而如果它期望参数值在某个范围内，例如某种长度的字符串或大于 0 的整数，那么它也应该那样描述。并非所有方法都仔细检查其参数的有效性；不进行有效性检查也没有编制关于可接受的输入范围的文档，这二者的结合为灾难埋下了隐患。

返回代码
Javadoc 使得描述返回值的意义变得很容易，但正如方法参数一样，@return 标记应该包括对可能返回的值范围的详细描述。对于对象取值的返回类型而言，它会返回空值吗？对于整数取值的返回类型而言，结果会限制在一个已知值或非负值的集合上吗？任何返回代码都有特殊意义吗，例如从 java.io.InputStream.read() 返回 -1 表示文件结束符？返回代码会被用来表示例如如果无法找到表项则返回空值那样的错误条件吗？

异常
标准 doclet 复制方法的 throws 子句，但 Javadoc @throws 标记应该更为具体。例如，NoSuchFileException 是 IOException 的子类，但 java.io 中的大多数方法却只被声明为抛出 IOException。然而，方法可能独立于其它 IOException 而抛出 NoSuchFileException，这是调用者要了解的很有用的事实 ? 它应该被包括在 Javadoc 中。还应该指出抛出各种异常类的实际错误条件，以便调用者知道在给定异常被抛出时该采取什么纠正措施。应该用 @throws 标记对方法可能抛出的每个经检查的或未经检查的异常编制文档，并对引发抛出异常的条件编制文档。

前置条件、后置条件和不变条件
当然，您应该对方法对对象状态的影响编制文档。但您可能需要编制得更详细一些，描述方法的前置条件、后置条件和类不变条件。前置条件是在调用方法前对对象状态的约束；例如，调用 Iterator.next() 的前置条件是 hasMore() 为真。后置条件是方法调用完成后对对象状态的约束，例如在调用 add() 之后 List 不能为空。不变条件是对对象状态的一种约束，它保证该状态始终为真，例如 Collection.size() == Collection.toArray().length()。

诸如 jContract 之类的按契约设计（Design-by-contract）工具允许您使用特殊注释指定前置条件、后置条件和类不变条件，这类工具然后生成额外代码来强制这些约束。无论您是否使用工具来强制这些期望条件，对这些约束编制文档可以让用户知道要安全地使用类，他们可以做些什么。

副作用
有时候，方法除了改变对象状态之外还会有其它副作用，例如改变相关对象、JVM 或底层计算平台的状态。例如，所有执行 I/O 的方法都有副作用。有些副作用是无害的，例如保留类处理的请求的记数。另外一些副作用则会对程序性能和正确性产生重大影响，例如修改传递给方法的对象的状态，或存储对该对象的引用的副本。诸如修改相关对象的状态或存储对作为方法参数传递的对象的引用之类的副作用应该编制文档。

方法联接
方法联接意味着类中的两个方法相互依赖，并且都对对方的行为做了假定。发生方法联接的一种常见情形是：方法在内部使用同一个类的 toString 方法，并假定 toString 将以特别的方法格式化对象状态。如果该类已经子类化并且 toString 方法被重写了，那么这种情形可能引起问题；另一个方法会突然不能正常工作，除非它也被重写。如果您的方法依赖于其它方法的实现行为，那么需要对那些依赖性编制文档。而且，如果类已子类化，那么可以以一致的方式重写两种方法以便使子类仍能正常工作。

线程安全
应该编制文档的最重要的行为之一是线程安全，而对它几乎从未编制文档。这个类是线程安全的吗？如果不是，那么是否可以通过用同步封装调用来使其线程安全吗？这些同步必须同特定管程相关联，还是任何一直使用的管程都可以使用呢？方法获得了对于类外部是可见的对象的锁吗？

线程安全实际上不是二进制属性；线程安全有几种可标识的等级。对线程安全编制文档，或者甚至确定线程安全的等级并非总是很容易。但未能进行这一工作将导致严重的问题；在并发应用程序中使用非线程安全类可能引起零星的故障，这些故障常常直到部署时才出现（那时暴露应用程序以便装入）。而且将额外锁定封装在已经是线程安全的类周围会影响性能，甚至引起死锁。

Josh Bloch 在他的 Effective Java Programming Language Guide（参阅参考资料）一书中对类的线程安全等级编制文档提供了有用的分类法。可以按照线程安全递减顺序将类归到下列某一组：不可变、线程安全、有条件的线程安全、线程兼容和线程对立。

这种分类是一个极佳的框架，用于在并发访问情况下传递关于类行为的重要信息。不管您是否使用这一分类法都没关系，但您应该标识您的类意图显示的线程安全等级。我还建议：如果方法获得对一个对象的锁定，而该对象对于类自身的代码外部是可见的，那么您也应该就此编制文档，即使这只是一个“实现细节”，以便协助做出全局锁定顺序（global-lock-order）决策并防止死锁。

结束语
对类的行为编制文档远远不只是对每个方法做什么给出一行描述。有效的 Javadoc 应该包括对下列内容的描述：

类如何相互关联
方法如何影响对象的状态
方法如何将出错条件通知它们的调用者以及它们可能通知什么错误
类如何处理多线程应用程序中的使用
方法的参数作用域及其返回值的范围
另外，糟糕的文档（或甚至更糟糕，没有文档）会导致优秀的代码不可用或不可重用。通过在文档上花一些额外时间，您将为您的用户（可能是您自己）避免无数的挫折。

参考资料

单击文章顶部或底部的讨论来参加关于本文的论坛。


Sun 教程“How to Write Doc Comments for the Javadoc Tool”描述了 Javadoc 的规则和基本原理。


Josh Bloch 的 Effective Java Programming Language Guide 包含了有关编写更好代码的大量有用提示和指导原则。


Peter Haggar 的文章“Acquire multiple locks in a fixed, global order to prevent deadlock”（developerWorks，2000 年 9 月）描述了一种降低死锁风险的技术，但这种技术依赖于对锁定行为的有效的文档。


JContract 是一种强制类契约和类约束的商业工具。


文章“Exceptional Practices”（JavaWorld，2001 年 8 月）提供了编写 throws 子句的指导原则。


Jeremy Roschelle 的文章“Doclet your servlet”（JavaWorld，2001 年 3 月）描述了可以怎样使用定制 doclet 来为 servlet 更为详细的文档。


John Farrell 在“Make bad code good”（JavaWorld，2001 年 3 月）中谈到了 Javadoc 在重构 Java 类方面的重要性。


Scott Ambler 为编制方法文档提供了便捷的检查表（developerWorks，2001 年 8 月）。


Javadoc doclet API 让您编写定制 Javadoc 插件来生成不同形式的文档，或甚至从 Javadoc 注释自动生成代码或模式。[@more@]