4.9　编写文档

受益于优秀文档的同时，应该编写优秀的文档来作为回报。Java 语言提供了一项很好的功能，即可以在源代码中嵌入文档。这让你能够在编写代码的同时编写文档，同时，更容易在修改代码时确保文档与代码一致。

可用工具 Javadoc 自动提取包含在源代码中的文档，并生成格式良好的 HTML。这个工具包含在标准 Java 开发环境中，被大家广泛使用。事实上，Java 库的在线文档就是用 Javadoc 生成的。

Javadoc 扫描源代码文件以查找格式特殊的文档注释——也称为 Javadoc 注释。这种注释以 /**（两个星号）打头，并以 */（一个星号）结尾，位于它们之间的所有内容都被视为文档。

下面的类定义包含两条 Javadoc 注释，其中一条是针对类的，另一条是针对方法 main 的：

  1. /**
  2.  * 演示print和println的示例程序
  3.  */
  4. public class Goodbye {
  6.     /**
  7.      * 打印问候语
  8.      */
  9.     public static void main(String[] args) {
  10.         System.out.print("Goodbye, "); // 请注意其中的空格
  11.         System.out.println("cruel world");
  12.     }
  13. }

类注释阐述了类的目的，而方法注释阐述了方法的作用。

注意，这个示例还包含了一条以 // 打头的内嵌注释。一般而言，内嵌注释是对程序复杂部分进行诠释的短语，旨在帮助其他程序员理解和维护源代码。

相反，Javadoc 注释更长，通常是完整的句子。它们阐述每个方法的功能，但不涉及其工作原理的细节，旨在让人无需查看源代码就能使用这些方法。

要想让源代码易于理解，合适的注释和文档是必不可少的。另外别忘了，对于你编写的代码，未来阅读得最多的人就是你自己，届时你定将庆幸自己编写了优秀的文档。