描述一个方法所抛出的异常，是正确的使用这个方法时所需要文档的重要组成部分，因此花点时间仔细的为每个方法抛出的异常建立文档是特别重要的。
始终要单独地声明检查时异常,并且使用javadoc的@throws标记,准确地记录下抛出每个异常的条件.如果方法抛出多个异常类,不要使用它抛出异常类的父类.永远不要声明方法”throwsException”,或更糟糕的声明它”throw Throwable”.这样的声明没有给开发者关于”这个方法抛出哪些异常”的任何有用信息,实际上掩盖了该方法在同样的执行环境下可能抛出的任何其他异常， 因此会妨碍该方法的使用。
使用javacdoc的@throws标签记录下一个方法可能抛出的未受检异常,但是不要使用throws关键字将未受检的异常包含在方法的声明中.使用API的程序员必须知道哪些异常是需要受检的,哪些是不需要受检的,因为两种情况下责任是不同的.当缺少由throws声明产生的方法标头时,有javadoc的@throws标签产生的文档就会提供明显的提示信息,以帮助程序员区分受检的异常和未受检的异常.
总而言之，要为你编写的每个方法所抛出的每个异常建立文档.对受检的异常和未受检的异常,以及对于抽象和具体的方法都一样.要为每个受检的异常提供单独的throws字句,不要为未受检的异常提供throws语句.如果没有为可以抛出的异常建立文档,那么其他开发人员很难或者根本不可能有效使用你的类或接口.
网友评论