Java语言按照Javadoc注释约定采用了一种集成的方法来进行API文档编制.Javadoc工具可以帮助生成好的API文档,然而大多数
Java API文档却很糟糕。因为它是源代码的一部分,所以API的文档编制职责最终还是落到了工程师身上。在本文中,布莱恩对Java
文档编制实践的当前状态进行了严厉的批评,同时提供了一些关于如何编写更有用的Javadoc的准则。
对于大多数Java类库来说,Javadoc 是唯一的文档。而且,除了商业软件组件之外,许多Java类不会用到Javadoc。虽然Javadoc作为API 参考工具很出色,但对于了解类库是如何组织的和应该如何使用它来说,它却是一种十分差劲的方法。并且即便用了 Javadoc,它通常只包含有关方法完成了什么的最基本信息,而忽略了诸如错误处理,参数及返回值的作用域和范围,线程安全,锁定行为,前置条件,后置条件,不变条件或副作用之类的重要特性。
向 Javadoc学习
对于包括大多数开放源码包和大多数内部开发的组件在内的许多Java工具而言,实际情况是:包括Javadoc 在内,几乎所有类库或组件都不具有有效的文档。这就意味着开发人员要从Javadoc学习使用工具,而且我们应该考虑根据这一现实组织我们的 Javadoc。我经常开玩笑说:现在,Java程序员需要具备的最重要的技能之一是熟练地使用谷歌和Javadoc来对那些文档编制得十分糟糕的 API进行“逆向工程”。这可能是真的,但却并不十分好笑。
大多数Java 包都有某种“根”对象,它是在得到该工具内的任何其它对象之前,必须创建的第一个对象。在JNDI中,该根对象是上下文,而在JMS和JDBC 中,它是连接。如果有人告诉您JDBC中的基础对象是连接,以及如何获得这一对象,那么接着您很可能会从Javadoc 中通过仔细察看Javadoc中可用的方法列表找到如何创建并执行声明,以及如何迭代生成的ResultSet。但您如何知道获得 连接是您的第一步呢? Javadoc在包内按照字母顺序组织类,在类中按照字母顺序组织方法。遗憾的是,Javadoc 中没有神奇的“从这里开始(从这里开始)”记号把读者带到浏览API 的逻辑开始位置。
包描述
最接近”从这里开始”记号的是包描述,但它却很少得到有效的使用。如果将文件package.html 与源代码一起放在一个包中,那么标准的doclet会将已生成的package-summary.html 文件中的内容连同类列表一起放在该包内。遗憾的是,生成我们都很熟悉的HTML文档的标准doclet 却无法使包描述易于找到。如果您单击左上窗格中的某个包,那么这会在左下窗格中产生方法列表,但并不会在主窗格中产生包的摘要吗? 必须单击左下窗格中的包名称来查看摘要。但不要紧,毕竟大多数包并没有包描述。
包文档是一个放置”从这里开始“文档的极好的地方,这一文档用来概述包做什么,主要摘要是什么以及从何处开始浏览包的 Javadoc。
类文档
除包文档之外,特定于类的文档对于帮助用户彻底了解新工具也能起到重要的作用。类文档当然应该包括此特定类做什么的描述,但还应该描述该类与包中的其它类如何关联,特别是要标识任何与该类相关的工厂类。例如,JDBC 中声明的类文档应该说明:声明是通过连接类的createStatement () 方法获得的。这样,如果一个新用户偶然进入声明页面,那么他会发现首先他需要获得 连接。对每个类都应用这一约定的包会迅速为用户指出根对象,用户因而能够得心应手。
因为Javadoc 是围绕对特定类进行文档编制而设计的,因此在Javadoc 中通常没有明显的位置来放置演示几个相关类一起使用的示例代码。但由于一味地侧重于特定类或方法的文档编制,我们失去了讨论如何组合包中内容的机会。如果对于根对象,在包文档或类文档中有一个演示一些基本用法的简单代码示例,则对于许多用户来说,将是非常有用的,例如,连接 类文档可以有一个简单示例,该示例获取连接,创建预编译语句,执行该语句并迭代结果集。从技术上说,这可能不属于连接 页面,因为它还描述了包中的其它类。然而,尤其是当结合了上面那种引用当前类所依赖的类的技术时,用户才能非常迅速地找到获取简单的实用示例的途径,不管类的组织方式如何。
糟糕的文档==糟糕的代码
对于大多数Java类库来说,除了那些作为打包组件出售的商业产品之外,要么没有 Javadoc,要么非常糟糕。由于存在的事实是对于大多数包来说,Javadoc 是我们拥有的唯一文档,这基本上意味着使我们自己陷入了这样的困境:除了作者之外,其他人没法使用我们的大部分代码? 如果不付出重大的“考古”一样的努力,至少会这样。
对于大多数Java类库来说,Javadoc 是唯一的文档。而且,除了商业软件组件之外,许多Java类不会用到Javadoc。虽然Javadoc作为API 参考工具很出色,但对于了解类库是如何组织的和应该如何使用它来说,它却是一种十分差劲的方法。并且即便用了 Javadoc,它通常只包含有关方法完成了什么的最基本信息,而忽略了诸如错误处理,参数及返回值的作用域和范围,线程安全,锁定行为,前置条件,后置条件,不变条件或副作用之类的重要特性。
向 Javadoc学习
对于包括大多数开放源码包和大多数内部开发的组件在内的许多Java工具而言,实际情况是:包括Javadoc 在内,几乎所有类库或组件都不具有有效的文档。这就意味着开发人员要从Javadoc学习使用工具,而且我们应该考虑根据这一现实组织我们的 Javadoc。我经常开玩笑说:现在,Java程序员需要具备的最重要的技能之一是熟练地使用谷歌和Javadoc来对那些文档编制得十分糟糕的 API进行“逆向工程”。这可能是真的,但却并不十分好笑。
大多数Java 包都有某种“根”对象,它是在得到该工具内的任何其它对象之前,必须创建的第一个对象。在JNDI中,该根对象是上下文,而在JMS和JDBC 中,它是连接。如果有人告诉您JDBC中的基础对象是连接,以及如何获得这一对象,那么接着您很可能会从Javadoc 中通过仔细察看Javadoc中可用的方法列表找到如何创建并执行声明,以及如何迭代生成的ResultSet。但您如何知道获得 连接是您的第一步呢? Javadoc在包内按照字母顺序组织类,在类中按照字母顺序组织方法。遗憾的是,Javadoc 中没有神奇的“从这里开始(从这里开始)”记号把读者带到浏览API 的逻辑开始位置。
包描述
最接近”从这里开始”记号的是包描述,但它却很少得到有效的使用。如果将文件package.html 与源代码一起放在一个包中,那么标准的doclet会将已生成的package-summary.html 文件中的内容连同类列表一起放在该包内。遗憾的是,生成我们都很熟悉的HTML文档的标准doclet 却无法使包描述易于找到。如果您单击左上窗格中的某个包,那么这会在左下窗格中产生方法列表,但并不会在主窗格中产生包的摘要吗? 必须单击左下窗格中的包名称来查看摘要。但不要紧,毕竟大多数包并没有包描述。
包文档是一个放置”从这里开始“文档的极好的地方,这一文档用来概述包做什么,主要摘要是什么以及从何处开始浏览包的 Javadoc。
类文档
除包文档之外,特定于类的文档对于帮助用户彻底了解新工具也能起到重要的作用。类文档当然应该包括此特定类做什么的描述,但还应该描述该类与包中的其它类如何关联,特别是要标识任何与该类相关的工厂类。例如,JDBC 中声明的类文档应该说明:声明是通过连接类的createStatement () 方法获得的。这样,如果一个新用户偶然进入声明页面,那么他会发现首先他需要获得 连接。对每个类都应用这一约定的包会迅速为用户指出根对象,用户因而能够得心应手。
因为Javadoc 是围绕对特定类进行文档编制而设计的,因此在Javadoc 中通常没有明显的位置来放置演示几个相关类一起使用的示例代码。但由于一味地侧重于特定类或方法的文档编制,我们失去了讨论如何组合包中内容的机会。如果对于根对象,在包文档或类文档中有一个演示一些基本用法的简单代码示例,则对于许多用户来说,将是非常有用的,例如,连接 类文档可以有一个简单示例,该示例获取连接,创建预编译语句,执行该语句并迭代结果集。从技术上说,这可能不属于连接 页面,因为它还描述了包中的其它类。然而,尤其是当结合了上面那种引用当前类所依赖的类的技术时,用户才能非常迅速地找到获取简单的实用示例的途径,不管类的组织方式如何。
糟糕的文档==糟糕的代码
对于大多数Java类库来说,除了那些作为打包组件出售的商业产品之外,要么没有 Javadoc,要么非常糟糕。由于存在的事实是对于大多数包来说,Javadoc 是我们拥有的唯一文档,这基本上意味着使我们自己陷入了这样的困境:除了作者之外,其他人没法使用我们的大部分代码? 如果不付出重大的“考古”一样的努力,至少会这样。
