跟我学（Effective Java 2）第62条:每个方法抛出的异常都要有文档

第62条:每个方法抛出的异常都要有文档

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

始终要单独的声明受检的异常，并且利用Javadoc的@throws标记，准确的记录下抛出每个异常的条件。如果一个方法可能抛出多个异常类，则不要使用“快捷方式”声明他会抛出这些异常类的某个超类。这样的声明不仅没有为程序员提供关于“这个方法能够抛出哪些异常”的任何指导信息，而且大大的妨碍了该方法的使用，因为他实际上掩盖了该方法在同样的执行环境下可能抛出的任何其他异常。

虽然Java语言本身并不要求程序员你为一个方法声明他可能会抛出的未受检异常，但是，如同受检异常一样，仔细的为他们建立文档是非常明智的。未受检的异常通常代表编程上的错误，让程序员了解所有这些错误都有助于帮助他们避免犯这样的错误。对于方法可能抛出的未受检异常，如果将这些异常信息很好的组织成列表文档，就可以有效地描述出这个方法被成功执行的前提条件。

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

使用Javadoc的@throws标签记录下一个方法可能抛出的每个未受检异常，但是不要使用throws关键字将未受检的异常包含在方法的声明中。使用API的程序员必须知道哪些异常是需要受检的，哪些是不需要受检的，这很重要，因为这两种情况下他们的责任是不同的。当缺少由throws声明产生的方法标头时，由Javadoc的@throws标签所产生的文档就会提供明显的提示信息，以帮助程序员区分受检的异常和未受检的异常。

如果一个类中的许多方法出于同样的原因而抛出同一个异常，在该类的文档注释中对这个异常建立文档，这是可以接受的，而不是为每个方法单独建立文档。

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