Java: best practice for declaring a thrown exception
Let's say you have some kind of method that declares to throw a thrown exception
EDIT : say it's not you who developed this method, but the authors of a very respectable framework (Spring, aekhm!), You just call it
void someMethod() throws UncheckedException;
My first question:
- Is there any reason other than clarity for declaring this thrown exception in the throws clause?
Let's say you have another method calling someMethod
void someOtherMethod() {
someMethod()
}
My second question:
- What would be the best practice in deciding whether to declare throwing
UncheckedException
insomeOtherMethod
?
A little background:
Spring Framework Exception is based on unchecked exceptions. So, for example, some methods throw (and declare it in throws
) a DataAccessException. If my code uses these calls, should it or should it not declare to throw these exceptions? And why?
source to share
There is no need to declare unhandled exceptions in the throws ...
method clause . As stated in the Java Language Specification , "It is permitted, but not required, to mention uncontrolled exception classes in the throws clause."
It is common practice to list Exceptions in your Javadoc if you expect users of your API to run into them. A common example of this is a list of reasons it might be selected IllegalArgumentException
.
If you wrap one method in another, use the Effective Java method to throw exceptions suitable for the abstraction layer (clause 61). This should apply to both checked exceptions and expected unchecked exceptions.
source to share
I recommend reading Chapter 9 in Effective Java. You will get your questions answered and you will enjoy a great reading.
In particular, questions for you:
Use the Javadoc @throws tag to document every unchecked exception that a method can throw, but don't use the throw keyword to include unchecked exceptions in a method declaration
source to share
The best practice is not to declare thrown exceptions at all. You don't see methods like this:
public void foo() throws NullPointerException {...}
You should only use throws for Checked Exceptions
. Speaking throws
, do you expect that klinet will process your exception by any means, and it is wrong forUnchecked Exceptions
EDIT:
There has been lively discussion in the comments, so just to clarify: you don't have to declare Unchecked Exceptions
, which doesn't mean you can't, although in most cases you shouldn't. I prefer to mention them in the javadoc style comments rather than a suggestion throws
. There are many other examples where you usually shouldn't be doing something, but in some cases you may need to. In my opinion the bottom line is: no, you shouldn't list Unchecked Exceptions
in throws clause
.
source to share
In my opinion, the best practice is not to use throws in the method head for an unchecked exception, but remember to document every exception (checked or not) your method throws:
/**
* Some doc
* @throws IllegalArgumentException if ...
*/
public void m() {
//...
throw new IllegalArgumentException();
}
source to share
Documenting your API is a good thing, and either declaring throws or adding @throws to your javadoc is good practice. It just makes things more obvious to the reader, which is never a bad thing. I don't always do this, but generally you want people to know that something can fail. I wouldn't do it for NPE, but things like input validation errors or authorization errors are what you want to document.
source to share