Effective Java(2nd Edition) Item 62 归档方法所抛出的异常(译文)
2008-12-19 13:20
561 查看
文档对正确使用方法是必要的,关于方法抛出异常的描述是文档的重要部分,所以,值得你花些时间,并仔细归档每个方法所抛出的异常。
请总是声明每个受检查的异常,并且使用Javadoc标签@throws精确归档异常抛出的条件。请不要为了投机取巧而声明方法抛出的几个异常的超类。作为极端的例子,请不要在方法声明中用”throws Exception”,或更糟的,用“throws Throwable“。这样做,不仅无助于指导方法的使用者应如何处理所捕获的异常,从且极大地妨碍了方法的使用,这样做还会模糊方法抛出的其它任何异常。
虽然语言并不要求程序员在方法中声明每个可能抛出的非受检查的异常,但与受检查的异常一样细心地归档它们仍是明智的。未受检查的异常一般表示程序错误(Item 58),让程序员尽量熟悉这些错误有助于帮助他们避免这些错误。对方法所抛出异常的好的文档描述了方法成功执行的前置条件,每个方法的文档均有描述其前置条件,这是归档的基础,为未受检查的异常归档是描述前置条件的最好方法。
对接口中的方法所抛出的异常归档尤为重要。这个文档是接口一般契约(general contract)的一部分,为该接口多个不同实现担供共同形为成为可能。
请使用Javadoc的@throws标签为方法抛出的每个未受检查的异常归档,请不要在方法的声明中使用关键字throws包含未受检查的异常。让使用你API的程序员知道哪些异常是受检查的哪些不是受检查的是重要的,因为这两种情形表示了不同职责。对方法声明中没有throws的异常,通过Javadoc的throws标签作了文档化,会带来很强的视觉暗示,从而有助于程序员区别受检查异常与未受检查异常。
请注意,为每个方法可能抛出的所有未受检查的异常归档是一种理想,在真实世界中,并不总是可以做到的。如果一个类作了版本更新,其一个对外(exported)方法抛出了另外的未受检查异常,这并没有背离源程序或二进制兼容。设想两个独立完成的类,其中一个调用了另一个的方法。前者类的作者仔细归档了每个方法可能抛出的未受检查的异常,但如果后面的类在新版本中抛出了新的未受检查的异常,后面的类也就很可能抛出新的未受检查的异常,但还没对其归档。
如果一个异常被同一个类的许多方法因为同样的原因而抛出,哪么就可以在类的文档注释中进行文档化,而不用在每个方法文档化。在类的文档注释中可以这样:“如果传入的参数是null引用,则这个类的所有方法将抛出NullPointerException”,这种写法或诸多此类的写法都很好。 总之,请为你所写的每个方法所可能抛出的每个异常文档化。无论是对受检查的异常还是对未受检查的异常,无论是抽象方法还是具体方法,都应如此。在thrwos子句中包含每个受检查的异常,不包含未受检查的异常。如果你没有很好的为你方法抛出的异常文档化,哪么其他人要有效地使用你的类或接口就变得困难或者是不可能的。
请总是声明每个受检查的异常,并且使用Javadoc标签@throws精确归档异常抛出的条件。请不要为了投机取巧而声明方法抛出的几个异常的超类。作为极端的例子,请不要在方法声明中用”throws Exception”,或更糟的,用“throws Throwable“。这样做,不仅无助于指导方法的使用者应如何处理所捕获的异常,从且极大地妨碍了方法的使用,这样做还会模糊方法抛出的其它任何异常。
虽然语言并不要求程序员在方法中声明每个可能抛出的非受检查的异常,但与受检查的异常一样细心地归档它们仍是明智的。未受检查的异常一般表示程序错误(Item 58),让程序员尽量熟悉这些错误有助于帮助他们避免这些错误。对方法所抛出异常的好的文档描述了方法成功执行的前置条件,每个方法的文档均有描述其前置条件,这是归档的基础,为未受检查的异常归档是描述前置条件的最好方法。
对接口中的方法所抛出的异常归档尤为重要。这个文档是接口一般契约(general contract)的一部分,为该接口多个不同实现担供共同形为成为可能。
请使用Javadoc的@throws标签为方法抛出的每个未受检查的异常归档,请不要在方法的声明中使用关键字throws包含未受检查的异常。让使用你API的程序员知道哪些异常是受检查的哪些不是受检查的是重要的,因为这两种情形表示了不同职责。对方法声明中没有throws的异常,通过Javadoc的throws标签作了文档化,会带来很强的视觉暗示,从而有助于程序员区别受检查异常与未受检查异常。
请注意,为每个方法可能抛出的所有未受检查的异常归档是一种理想,在真实世界中,并不总是可以做到的。如果一个类作了版本更新,其一个对外(exported)方法抛出了另外的未受检查异常,这并没有背离源程序或二进制兼容。设想两个独立完成的类,其中一个调用了另一个的方法。前者类的作者仔细归档了每个方法可能抛出的未受检查的异常,但如果后面的类在新版本中抛出了新的未受检查的异常,后面的类也就很可能抛出新的未受检查的异常,但还没对其归档。
如果一个异常被同一个类的许多方法因为同样的原因而抛出,哪么就可以在类的文档注释中进行文档化,而不用在每个方法文档化。在类的文档注释中可以这样:“如果传入的参数是null引用,则这个类的所有方法将抛出NullPointerException”,这种写法或诸多此类的写法都很好。 总之,请为你所写的每个方法所可能抛出的每个异常文档化。无论是对受检查的异常还是对未受检查的异常,无论是抽象方法还是具体方法,都应如此。在thrwos子句中包含每个受检查的异常,不包含未受检查的异常。如果你没有很好的为你方法抛出的异常文档化,哪么其他人要有效地使用你的类或接口就变得困难或者是不可能的。
相关文章推荐
- Effective Java(2nd Edition) Item 59 避免使用不必要的受检查异常(译文)
- Effective Java(2nd Edition) Item 61 适当抽象抛出的异常(译文)
- Effective Java(2nd Edition) Item 63 译文
- Effective Java(2nd Edition) Item 58 受检查异常用作可恢复条件,运行时异常用作程序错误
- Effective Java(2nd Edition) Item 60 优先使用标准异常(译文)
- Effective Java(2nd Edition) Item 48 如果需要精确结果,请避免使用float与double(译文)
- Effective Java(2nd Edition) Item 57 仅为例外条件使用异常(译文)
- Effective Java(2nd Edition) Item 46 for-each循环优于传统的for循环(译文)
- Effective Java(2nd Edition) Item 45 最小化局部变量的作用域(译文)
- Effective Java(2nd Edition) Item 45 最小化局部变量的作用域
- JUnit4测试方法异常抛出实例
- 利用反射原理调用方法抛出异常:argument type mismatch
- 在方法中抛出异常,使用throw关键字抛出异常
- 写一个方法void triangle(int a,int b,int c),判断三个参数是否能构成一个三角形。如果不能则抛出异常IllegalArgumentException,显示异常信息:a,b,
- 读书笔记 effective c++ Item 25 实现一个不抛出异常的swap
- 开启硬件加速之后,许多2D的绘制方法会抛出异常
- 第04章 异常处理 06 声明方法抛出的异常
- PHP 的异常处理、错误的抛出及回调函数等面向对象的错误处理方法
- 75_异常机制_声明异常throw_方法重写中异常的处理_手动抛出异常
- <Effective C++>:Item25:考虑写出一个不抛出异常的swap函数