建议：每个方法抛出的异常都要有文档。

男娘i 2024-02-18 21:41 29阅读 0赞

描述一个方法所抛出的异常，是正确使用这个方法时所需文档的重要组成部分。因此，花点时间仔细的为每个方法抛出的异常建立文档是特别重要的。  
**始终要单独的声明受检的异常，并且利用Javadoc的@throws标记，准确的记录下抛出每个异常的条件。**如果一个方法可能抛出多个异常类，则不要使用“快捷方式”声明他会抛出这些异常类的某个超类。永远不要声明一个方法“throws Exception”，或者更糟糕的是声明他“throws Throwable”，这是非常极端的例子。这样的声明不仅没有为程序员提供关于“这个方法能够抛出哪些异常”的任何指导信息，而且大大的妨碍了该方法的使用，因为他实际上掩盖了该方法在同样的执行环境下可能抛出的任何其他异常。  
虽然Java语言本身并不要求程序员你为一个方法声明他可能会抛出的未受检异常，但是，如同受检异常一样，仔细的为他们建立文档是非常明智的。未受检的异常通常代表编程上的错误，让程序员了解所有这些错误都有助于帮助他们避免犯这样的错误。对于方法可能抛出的未受检异常，如果将这些异常信息很好的组织成列表文档，就可以有效地描述出这个方法被成功执行的前提条件。每个方法文档应该描述他的前提条件，这是很重要的，在文档中记录下未受检的异常是满足前提条件的最佳做法。  
对于接口中的方法，在文档中记录下来他可能抛出的未受检异常显得尤为重要。这份文档构成了该接口的通用约定的一部分，他指定了该接口的多个实现必须遵循的公共行为。  
**使用Javadoc的@throws标签记录下一个方法可能抛出的每个未受检异常，但是不要使用throws关键字将未受检的异常包含在方法的声明中。**使用API的程序员必须知道哪些异常是需要受检的，哪些是不需要受检的，这很重要，因为这两种情况下他们的责任是不同的。当缺少由throws声明产生的方法标头时，由Javadoc的@throws标签所产生的文档就会提供明显的提示信息，以帮助程序员区分受检的异常和未受检的异常。  
应该注意到，为每个方法可能抛出的所有未受检异常建立文档是很理想的，但是在实践中并非总能做到这一点。当类被修订之后，如果有个导出方法被修改了，他将会抛出额外的未受检异常，这不算违反源代码或者二进制兼容性。假设一个类调用了另一个独立类中的方法。第一个类的编写者可能会为每个方法抛出的未受检异常仔细的建立文档。但是，如果第二个类被修订了，抛出了额外的未受检异常，很有可能第一个类（他并没有被修订）就会把新的未受检异常传播出去，尽管他并没有声明这些异常。  
**如果一个类中的许多方法出于同样的原因而抛出同一个异常，在该类的文档注释中对这个异常建立文档，这是可以接受的，而不是为每个方法单独建立文档。**一个常见的例子是NullPointerException。如果类的文档注释中有这样描述：“如果null对象引用被传递到任何一个参数中，这个类中的所有方法都会抛出NullPointerException”，或者有其他类似语句，这是可以的。  
总而言之，要为你编写的每个方法所能抛出的每个异常建立文档。对于未受检和受检的异常，以及对于抽象的和具体的方法也都一样。要为每个受检异常提供单独的throws子句，不要为未受检的异常提供throws子句。如果没有为可以抛出的异常建立文档，其他人就很难或者根本不可能有效地使用你的类和接口。