每个方法抛出的所有异常都要建立文档

  描述一个方法所抛出的异常，是正确使用这个方法时所需文档的重要组成部分。因此，花点时间仔细地为每个方法抛出的异常建立文档是特别重要的（第 56 项）。

  始终要单独地声明受检的异常，并且利用 Javadoc 的@throws 标记，准确地记录下抛出每个异常的条件 。如果一个方法可能抛出多个异常类，则不要使用“快捷方式（shortcut）”声明它会抛出这些异常类的某个超类。永远不要声明一个方法“throws Exception”，或者更糟糕的是声明它“throws Throwable”，这是非常极端的例子。这样的声明不仅没有为程序猿提供关于“这个方法能够抛出哪些异常”的任何指导信息，而且大大地妨碍了该方法的使用，因为它实际上掩盖了该方法在同样的执行环境下可能抛出的任何其他异常。这个建议的一个例外是 main 方法，它可以安全地声明为抛出 Exception，因为它只由 VM 调用。

  虽然 Java 语言本身并不要求程序猿为一个方法声明它可能会抛出的未受检异常，但是，如同受检异常一样，仔细地为它们建立文档是非常明智的。未受检的异常通常代表编程上的错误（第 70 项），让程序猿了解这些错误有助于帮助他们避免犯这样的错误。对于方法可能抛出的未受检异常，如果将这些异常信息很好地组织成列表文档，就可以有效地描述出这个方法被成功执行的前提条件（precondition）。每个方法的文档应该描述它的前提条件（第 56 项），并在文档中记录下未受检的异常是满足此要求的最佳方式。

  对于接口中的方法，在文档中记录下它可能抛出的未受检异常显得尤为重要。这份文档构成了该接口*通用约定（general contract）*的一部分，它指定了该接口的多个实现必须遵循的公共行为。

  使用 Javadoc 的@throws 标签记录下一个方法可能抛出的每个未受检异常，但是不要在未受检异常上使用 throws 关键字 。使用 API 的程序猿必须知道哪些异常是需要受检的，哪些是不需要受检的，这很重要，因为这两种情况下他们【程序猿】的责任是不同的。由 Javadoc @throws 标记生成的文档在方法声明中没有相应的 throws 子句，这就为程序猿提供了一个强大的提示信息，即：这是一个未受检异常。

  应该注意到的一点是，为每个方法可能抛出的所有未受检异常建立文档是很理想的，但是在实践中并非总能做到【理想很美好，现实很骨感】。当类被修订之后，如果有个导出方法被修改了，它将会抛出额外的未受检异常，这不算违反源代码或者二进制兼容性。假设一个类调用了另一个独立类中的方法。第一个类的编写者可能会为每个方法抛出的未受检异常仔细地建立文档，但是，如果第二个类被修订了，抛出了额外的未受检异常，很有可能第一个类（它并没有被修订）就会把新的未受检异常传播出去，尽管它并没有声明这些异常。

  如果一个类中的许多方法出于同样的原因而抛出同一个异常，则可以在类的文档注释中记录异常 ，而不是为每个方法单独建立文档。一个常见的例子是 NullPointerException。如果类的文档注释有这样的描述：“All methods in this class throw a NullPointerException if a null object reference is passed in any parameter（如果 null 对象引用被传递到任何一个参数中，这个类中的所有方法都会抛出 NullPointerexception”，或者有其他类似的语句，这是可以的。

  总而言之，要为你编写的每个方法所能抛出的每个异常建立文档。对于未受检的和受检的异常，以及对于抽象的和具体的方法也一样。此文档应采用 doc 注释中的@throws 标记的形式。 为每个受检异常提供单独的 throws 子句，不要为未受检的异常提供 throws 子句。如果没有为可能抛出的异常建立文档，其他人就很难或者根本不可能有效地使用你的类和接口。

• 第 73 项：抛出与抽象对应的异常
• 第 75 项：在细节消息中包含失败-捕获信息