Java 理论和实践：我必须对那些内容进行文档编制吗？

核心提示：java 语言按照 Javadoc 注释约定采用了一种集成的方法来进行 API 文档编制，Javadoc 工具可以帮助生成好的 API 文档，Java 理论和实践：我必须对那些内容进行文档编制吗？，然而大多数 Java API 文档却很糟糕，因为它是源代码的一部分，就和它一样，为了改善我们生产的软件的可靠性和可重用性，

　　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 文档也必须成为开发过程的一个集成部分。