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子句中分别声明每一个检查异常，但不要声明未检查异常。若是未记录方法可能抛出的异常，其余人将很难或不可能有效地使用你的类和接口。