ITEM 74: DOCUMENT ALL EXCEPTIONS THROWN BY EACH METHOD
对方法抛出的异常的描述是该方法文档的重要部分。因此，花时间仔细记录每个方法抛出的所有异常是非常重要的(item 56)。
我们应当声明已检查的异常，并使用 Javadoc @throws标记精确记录抛出每个异常的条件。不要采取这样的捷径：声明一个方法抛出它可以抛出的多个异常类的某个超类。作为一个极端的例子，不要声明一个公共方法会抛出异常，或者更糟的是，抛出 Throwable。除了拒绝向用户提供任何关于方法能够抛出异常的指导之外，这样的声明还会极大地阻碍方法的使用，因为它掩盖了在同一上下文中可能抛出的任何其他异常。这个建议的一个例外是 main 方法，它可以安全地声明为抛出 Exception，因为它只被VM调用。
虽然 Java 不要求程序员声明方法能够抛出的未检查异常，但是明智的做法是像记录已检查异常一样仔细地记录它们。未经检查的异常通常表示编程错误(item 70)，让程序员熟悉他们可能会犯的所有错误可以帮助他们避免这些错误。一个记录良好的方法可以抛出的未检查异常列表描述了成功执行的先决条件。每个公共方法的文档都必须描述其先决条件(item 56)，而记录未检查的异常是满足这一需求的最佳方式。尤其重要的是，接口中的方法要记录它们可能抛出的未检查异常。该文档构成了接口通用契约的一部分，并支持接口的多个实现之间的公共行为。
使用 Javadoc @throws 标记来记录方法可能抛出的每个异常，但不要对未检查的异常使用throws 关键字。使用您的API的程序员应该知道方法可能抛出哪些检查异常，哪些未检查异常，这是很重要的，因为程序员在这两种情况下的职责是不同的。由 Javadoc @throws标记生成的文档在方法声明中没有包含相应的 throws子句，它向程序员提供了一个强烈的可视化提示，即未检查异常。
应该注意的是，记录每个方法可能抛出的所有未检查异常是一种理想的做法，在现实世界中并不总是可以实现的。当类经历修订时，如果修改导出的方法以抛出额外的未检查异常，这并不违反源代码或二进制兼容性。
假设一个类从另一个独立编写的类调用一个方法。前类的作者可能会仔细记录所有的每个方法抛出未经检查的异常，如果后者类修改时添加了新的未检查异常，很可能前类(未经修订)将传播新的未经检查的异常，尽管它没有记录这个新的异常。
如果一个类中的许多方法出于相同的原因引发异常，您可以在类的文档注释中记录异常，而不是为每个方法单独记录异常。一个常见的例子是NullPointerException。对于类的文档注释来说，“如果在任何参数中传递了null对象引用，则该类中的所有方法都会抛出NullPointerException”，或者类似的文字。
总之，记录您编写的每个方法可能抛出的每个异常。对于未检查异常和已检查异常，对于抽象方法和具体方法都是如此。这个文档应该采用文档注释中的@throw标记的形式。在方法的throws子句中分别声明每个检查过的异常，但不要声明未检查过的异常。如果没有记录方法可能抛出的异常，其他人将很难或不可能有效地使用您的类和接口。
ITEM 74: 在文档中记录方法抛出的所有异常
©著作权归作者所有,转载或内容合作请联系作者
- 文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
- 文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
- 文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
推荐阅读更多精彩内容
- 描述方法抛出的异常是正确使用方法所需文档的重要部分。因此，花时间仔细记录每个方法抛出的所有异常是非常重要的(i...
- 当一个方法抛出一个与它所执行的任务没有明显关联的异常时，这是令人不安的。这种情况经常发生在方法传播由低层抽象抛...
- 黑色的海岛上悬着一轮又大又圆的明月，毫不嫌弃地把温柔的月色照在这寸草不生的小岛上。一个少年白衣白发，悠闲自如地倚坐...
