描述方法抛出的异常是正确使用方法所需文档的重要部分。因此，花时间仔细记录每个方法抛出的所有异常是非常重要的(item56)。
始终单独声明已检查异常，并使用Javadoc @throw标记精确地记录每次抛出异常的条件。不要使用快捷方式声明一个方法抛出它可以抛出的多个异常类的超类。作为一个极端的例子，不要声明公共方法抛出Exception，或者更糟，抛出Throwable。除了拒绝向方法的用户提供关于它能够抛出的异常的任何指导之外，这样的声明还极大地阻碍了方法的使用，因为它有效地掩盖了可能在相同上下文中抛出的任何其他异常。这个建议的一个异常是main方法，它可以安全地声明为抛出异常，因为它只被VM调用。
虽然该语言不要求程序员声明方法能够抛出的未检查异常，但明智的做法是像检查异常一样仔细地记录它们。未检查异常通常表示编程错误( item70 )，让程序员熟悉他们可能犯的所有错误可以帮助他们避免犯这些错误。方法可以抛出的未检查异常的良好文档列表有效地描述了成功执行的先决条件。每个公共方法的文档都必须描述它的先决条件(item56)，记录它的未检查异常是满足这个需求的最佳方法。
特别重要的是，接口中的方法要记录它们可能抛出的未检查异常。此文档构成接口通用契约的一部分，并支持接口的多个实现之间的公共行为。
使用Javadoc @throw标记记录方法可以抛出的每个异常，但是不要对未检查的异常使用throw关键字。重要的是，使用您的API的程序员知道哪些异常被检查，哪些异常被检查，因为程序员的职责在这两种情况下是不同的。Javadoc @throw标记生成的文档在方法声明中没有对应的throw子句，这向程序员提供了一个强烈的视觉提示，说明异常是未检查的。
应该注意的是，记录每个方法可以抛出的所有未检查异常是理想的，在现实世界中并不总是可以实现。类进行修订时，如果将导出的方法修改为抛出额外的未检查异常，这并不违反源或二进制兼容性。假设一个类从另一个独立编写的类调用一个方法。前类的作者可能会仔细记录所有的每个方法抛出未经检查的异常,如果后者类修改把额外的未经检查的异常,很可能前类(未经修订)将传播新的未经检查的异常,尽管它没有文档。
如果类中的许多方法出于相同的原因引发异常，可以在类的文档注释中记录异常而不是为每个方法单独编写文档。一个常见的例子是NullPointerException。一个类的文档注释可以这样说，
“如果在任何参数中传递null对象引用，该类中的所有方法都会抛出NullPointerException，”或类似的语句。
总之，记录您所编写的每个方法可能引发的每个异常。对于未检查异常和已检查异常以及抽象方法和具体方法都是如此。本文档应采用以下形式@在doc注释中抛出标记。在方法的throw子句中分别声明每个已检查的异常，但不要声明未检查的异常。如果您不能记录方法可能抛出的异常，其他人将很难或不可能有效地使用您的类和接口。
本文写于2019.7.22，历时1天
网友评论