Avoid @throws in javadoc
来源:互联网 发布:大华监控怎么连接网络 编辑:程序博客网 时间:2024/04/29 05:07
http://www.javapractices.com/topic/TopicAction.do?Id=171
Some argue that @throws should not be used at all. Instead, one may simply rely on the javadoc tool to automatically document all exceptions placed in the throws clause. However, others disagree.
Checked Exceptions :
- declaring only checked exceptions in the method's throws clause is a widely followed convention
- javadoc automatically generates basic documentation for all exceptions in the throws clause
- the documentation is generated with no extra effort on your part
- aren't typically placed in the method's throws clause.
- are very rarely caught by the caller.
- do not form part of the contract of the method, but rather represent what happens when the contract is broken. The caller cannot recover from such errors.
- almost always occur when a precondition on a parameter is not met. However, such conditions are almost always already documented in a @param tag.
- only place checked exceptions in the throws clause
- don't use @throws at all
In almost all cases, a @throws tag simply repeats verbatim conditions already stated in a @param tag, and doesn't add in any way to the specification of the method's behavior. Such repetition should be regarded with grave suspicion. When a change occurs, it's far too easy to forget to update the javadoc in two separate places.
A general comment regarding broken contracts can be stated once in the javadoc overview.html document :
"If the requirements or promises of any method's contract are not fulfilled (that is, if there is a bug in either the method or its caller), then an unchecked exception will be thrown. The precise type of such an unchecked exception does not form part of any method's contract."
Example
BasketBall has two constructors.
The first constructor includes several @throws tags in its javadoc. However, aside from the type of the unchecked exception, all of these @throwstags are logically equivalent to some previous statement in a @param tag. They add nothing to the contract.
The second constructor follows a different style. It has a single parameter, and the conditions on this parameter are stated once (and once only) in its @param tag.
public final class BasketBall { /** * @param aManufacturer non-null and has visible content. * @param aDiameter in centimeters, in the range 1..50. * @throws IllegalArgumentException if aDiameter not in given range. * @throws IllegalArgumentException if aManufacturer has no visible content. * @throws NullPointerException if aManufacturer is null. */ BasketBall(String aManufacturer, int aDiameter){ //..elided } /** * @param aDiameter in centimeters, in the range 1..50. */ BasketBall(int aDiameter){ //..elided } // PRIVATE private String fManufacturer; private int fDiameter;}
- Avoid @throws in javadoc
- avoid cache in jsp
- avoid jstl in loop
- avoid memory leak in osip
- Be specific in throws clause
- Avoid using blocking function in main thread
- Singleton in Spring to avoid reinvent wheels
- How to avoid Unicode pitfalls in Mojolicious
- Avoid non-default constructors in fragments
- How to avoid using() mistake in C#?
- Display XML in a javadoc
- throws
- What happend: Exception throws in the .ctor()?
- Javadoc in Eclipse failing to recognize packages
- thinking in java(day1)--javadoc
- How to see JavaDoc in IntelliJ IDEA?
- MS CRM Callouts Tip - Avoid Dead Loop in Callouts
- Memory leaks in C++ and how to avoid them
- Android 避免APP启动闪黑屏(Theme和Style)
- java_String类
- 正则表达式
- JAVA 的IO操作(五)简单文件复制
- Android binder -- Binder应用实例
- Avoid @throws in javadoc
- 关系型数据库与面向对象的冲突
- AppleScript学习笔记(六)处理程序Handler
- Avoid empty catch blocks
- Be specific in throws clause
- python安装及插件安装
- SICILY 1129. ISBN
- Beware of unknown root causes
- 傀儡进程内存Dump