Effective Java(2nd Edition) Item 62 归档方法所抛出的异常（译文）

文档对正确使用方法是必要的，关于方法抛出异常的描述是文档的重要部分，所以，值得你花些时间，并仔细归档每个方法所抛出的异常。

       请总是声明每个受检查的异常，并且使用Javadoc标签@throws精确归档异常抛出的条件。请不要为了投机取巧而声明方法抛出的几个异常的超类。作为极端的例子，请不要在方法声明中用”throws Exception”，或更糟的，用“throws Throwable“。这样做，不仅无助于指导方法的使用者应如何处理所捕获的异常，从且极大地妨碍了方法的使用，这样做还会模糊方法抛出的其它任何异常。

       虽然语言并不要求程序员在方法中声明每个可能抛出的非受检查的异常，但与受检查的异常一样细心地归档它们仍是明智的。未受检查的异常一般表示程序错误(Item 58)，让程序员尽量熟悉这些错误有助于帮助他们避免这些错误。对方法所抛出异常的好的文档描述了方法成功执行的前置条件，每个方法的文档均有描述其前置条件，这是归档的基础，为未受检查的异常归档是描述前置条件的最好方法。

       对接口中的方法所抛出的异常归档尤为重要。这个文档是接口一般契约(general contract)的一部分，为该接口多个不同实现担供共同形为成为可能。

       请使用Javadoc的@throws标签为方法抛出的每个未受检查的异常归档，请不要在方法的声明中使用关键字throws包含未受检查的异常。让使用你API的程序员知道哪些异常是受检查的哪些不是受检查的是重要的，因为这两种情形表示了不同职责。对方法声明中没有throws的异常，通过Javadoc的throws标签作了文档化，会带来很强的视觉暗示，从而有助于程序员区别受检查异常与未受检查异常。

       请注意，为每个方法可能抛出的所有未受检查的异常归档是一种理想，在真实世界中，并不总是可以做到的。如果一个类作了版本更新，其一个对外（exported）方法抛出了另外的未受检查异常，这并没有背离源程序或二进制兼容。设想两个独立完成的类，其中一个调用了另一个的方法。前者类的作者仔细归档了每个方法可能抛出的未受检查的异常，但如果后面的类在新版本中抛出了新的未受检查的异常，后面的类也就很可能抛出新的未受检查的异常，但还没对其归档。

       如果一个异常被同一个类的许多方法因为同样的原因而抛出，哪么就可以在类的文档注释中进行文档化，而不用在每个方法文档化。在类的文档注释中可以这样：“如果传入的参数是null引用，则这个类的所有方法将抛出NullPointerException”，这种写法或诸多此类的写法都很好。

       总之，请为你所写的每个方法所可能抛出的每个异常文档化。无论是对受检查的异常还是对未受检查的异常，无论是抽象方法还是具体方法，都应如此。在thrwos子句中包含每个受检查的异常，不包含未受检查的异常。如果你没有很好的为你方法抛出的异常文档化，哪么其他人要有效地使用你的类或接口就变得困难或者是不可能的。