Effective Java 第三版——74. 文档化每个方法抛出的所有异常

Tips
书中的源代码地址：https://github.com/jbloch/effective-java-3e-source-code
注意，书中的有些代码里方法是基于Java 9 API中的，所以JDK 最好下载 JDK 9以上的版本。

74. 文档化每个方法抛出的所有异常

描述方法抛出的异常，是正确使用方法所需文档的重要部分。因此，花时间为每个方法抛出的所有异常建立文档是非常重要的(条目 56)。

始终单独声明检查异常，并使用Javadoc @throw标签，精确地记录每次抛出异常的条件。不要使用“快捷方式”声明一个方法抛出它可以抛出的多个异常类的超类。作为一个极端的例子，不要声明公共方法抛出Exception类，或者更糟，抛出Throwable类。除了拒绝向方法的用户提供关于它能够抛出的异常的任何指导之外，这样的声明还极大地阻碍了方法的使用，因为它极大掩盖了可能在相同上下文中抛出的任何其他异常。这个建议的一个例外情况是main方法，它可以安全地声明为抛出Exception类，因为它只被虚拟机调用。

虽然Java语言不要求程序员声明方法能够抛出的未检查异常（unchecked exceptions），但明智的做法是像检查异常一样仔细地在文档中记录它们。未检查异常通常表示编程错误(条目 70)，让程序员熟悉他们可能犯的所有错误可以帮助他们避免犯这些错误。方法可以抛出的未检查异常的良好文档列表有效地描述了成功执行的先决条件。每个公共方法的文档都必须描述它的先决条件(条目 56)，记录它的未检查异常是满足这个需求的最佳方法。

特别重要的是，接口中的方法要在文档中记录它们可能抛出的未检查异常。此文档构成接口通用约定的一部分，并支持接口的多个实现之间的公共行为。

使用Javadoc @throw标签记录方法可以抛出的每个异常，但是不要对未检查的异常使用throws关键字。重要的是，使用你的API的程序员必须知道哪些方法是检查异常，哪些是未检查异常，因为程序员的责任在这两种情况下有所不同。Javadoc @throws标签生成的文档在方法声明中没有对应的抛出子句，这向程序员提供了一个强烈的视觉暗示，说明该异常是未检查异常。

应该注意的是，在文档中记录每个方法可以抛出的所有未检查异常是理想的，在现实世界中并不总是可以实现。当类进行修订时，如果将导出的方法修改为抛出额外的未检查异常，这并不违反源代码或二进制兼容性。假设一个类从另外一个独立编写的类调用一个方法。第一个类的作者可能会仔细记录所有的每个方法抛出未经检查的异常，但是如果第二个类的作者修改为额外的未经检查的异常，很可能第一个类(未经修订)将传播新的未经检查异常，尽管没有文档记录它们。

如果一个类中的许多方法出于相同的原因引发异常，可以在类的文档注释中记录异常，而不是为每个方法单独记录异常。一个常见的例子是NullPointerException。类的文档注释可以这样说：“如果在任何参数中传递了null对象引用，该类中的所有方法都会抛出NullPointerException”，或者类似的描述。

总之，在文档中记录你所编写的每个方法可能引发的每个异常。对于未检查异常、检查异常以及抽象方法和具体实现方法中都是如此。这个文档应该在文档注释中采用@throws标签的形式。在方法的throws子句中分别声明每个检查异常，但不要声明未检查异常。如果未记录方法可能抛出的异常，其他人将很难或不可能有效地使用你的类和接口。