Javadoc 利弊分析(from IBM)

核心提示：java 语言按照 Javadoc 注释约定采用了一种集成的方法来进行 API 文档编制，Javadoc 工具可以帮助生成好的 API 文档，Javadoc 利弊分析(from IBM)，然而大多数 Java API 文档却很糟糕，因为它是源代码的一部分，就和它一样，为了改善我们生产的软件的可靠性和可重用性，所以 AP

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