【第44条】每个方法抛出的异常都要有文档

    虽然在【第40条】中说到了，Java的throws语法的一大好处是，即使没有文档也可以知道要调用的方法都会抛出哪些异常。但是，绝对不推荐你这么做。一定要写好文档。

 

    通过@throws标签，逐个地声明每一个被检查的异常，并写清每一个异常被抛出的条件（这个是通过throws语句所了解不到的）。如果一个方法可能抛出多个异常，不要用它们共通的父类异常来表示。甚至，有人连会抛出哪些异常都不关，就干脆 throws Exception （更有甚者 throws Throwable）。这种极端的做法，可能是初学者偷懒的做法，也可能是习惯了.Net，对Java的checkedException深恶痛绝的程序员。但无论如何，不要这么做。

 

    这个恶习既不能让调用者知道此方法都会抛出哪些异常，也就更无法分别俘获这些异常，并根据不同状况做出不同的处理。但总有人会说，我并不关心哪里出了什么错，只要有错误，我的处理方式都是一样的：写日志，然后Down掉。面对这样的说辞我真的无言以对。碰巧，前些日我就碰到了这么一个项目组（我是这个项目的QA），还好（其实也没好到哪儿去）用的是.Net。

 

    对于RuntimeException，这就要有些“艺术”了。首先，throws声明中是不该包含它们的。其次，在文档的@throws标签中应该写出它们，并写好抛出条件。这对于写此方法的程序员来说又提高了要求，哪些RuntimeException可能出现，也不是可以“莫不关系”的了。这时候，你可能真的要让这该死的异常折磨得崩溃了，这不是“即想做婊子又要立牌坊”吗？天哪，请宽恕这些Java程序员吧。我也有些对.Net的做法感到理解了。

 

    对文档的要求，总是没有最好、只有更好。但最后，有一个让步：如果一个类中的许多方法都因相同的原因而抛出同样的异常，那么可以让步为在这个类的注释处写明文档，而不必每个方法都单独写。（其实Ctrl-C一下也并不难，啊）

 

 

 

【Effective Java 学习笔记】系列连载专题请见:
http://tonylian.iteye.com/categories/64208