Is there an advantage to declaring that a method throws an unchecked exception?

Question

If I have a method which throws an unchecked exception, e.g.:

void doSomething(int i) {
  if (i < 0) throw new IllegalArgumentException("Too small");
  // ...
}

is there any advantage to explicitly declaring that the method throws the exception, i.e.

void doSomething(int i) throws IllegalArgumentException {
  if (i < 0) throw new IllegalArgumentException("Too small");
  // ...
}

as opposed to (or in addition to) describing the behaviour in javadoc:

/**
 * This method does something useful.
 * @param i some input value
 * @throws IllegalArgumentException if {@code i < 0}
 */
void doSomething(int i) {
  if (i < 0) throw new IllegalArgumentException("Too small");
  // ...
}

The reasons why I would claim it is not useful to have the throws are:

• throws provides no information as to the circumstances under which the exception will be thrown, only that it might be thrown;
• Because it is an unchecked exception, I am not forced to handle the exception in calling code. I will only really know that it might be thrown if I go and look at the implementation of doSomething;
• The body of doSomething might invoke code which throws other types of unchecked exception; claiming that 'this method throws IllegalArgumentException' seems like it's only telling part of the story, potentially;
• If the method is non-final, it can be overridden such that the new implementation is declared to throw additional unchecked exceptions; you don't know which implementation you're invoking.

The reasons why I would claim it would be useful to have the throws are:

• It is reporting a problem that you might reasonably expect to encounter when invoking the method.

In short, I think that throws is unnecessary, but a javadoc description via @throws is useful. I would be interested to know others' opinion on this.

Answer 1

Exceptions are used for reporting 3 kinds of problems:

• Problems with the JVM and low-level runtime environment.
• Detected logic errors (bugs).
• Runtime problems that are impossible for the programmer to predict before trying an operation.

The first two kinds could happen at any time and there is essentially no good way of dealing with them. So there is no point in catching them, and thus no point in documenting them by declaring them in a throws clause. The third kind is the kind you want clients to know about and handle. For those, you want to clearly document that the exception might be thrown, with the implication that calling code must be prepared to handle the exception by catching it or correctly propagating it. You might use the throws clause to do that.

Now, to me it seems clear that the Java language designers intended checked exceptions, and only checked exceptions, to be used for that third kind. If that were always so, the simple answer to your question would be, no, do not declared unchecked exceptions in the throws clause.

But there is a complication. It is now quite common (popularised by Spring) to avoid checked exceptions for that third kind, and use unchecked exceptions in almost all cases. If you are programming in that style, using the throws clause to declare unchecked exceptions could be helpful.

Answer 2

When you state that a method throws an exception you are saying to the caller:

You have two choices:

1. Redeclare yourself as throwing the same exception.
2. Catch the exception and deal with it.

In case 1 it may remind user to implement a finally - which could be a bonus.

In case 2 it focuses the mind on the exception which could also be a bonus.

If you hide that possibility then neither of the above reminders occur to the user.

To me one may unnecessarily clutter up their code while the other keeps it sweet and simple. However, one encourages focus on potential issues while the other may leave you in blissful ignorance.

Bottom line - Ask yourself how irritating it will be to declare the exception as thrown (e.g. should you declare throws NullPointerException? - NO!) and is this irritation balanced by the upside of focusing the users mind on catch, finally and throws.

Answer 3

If the user of your API cannot see your source code he wouldn't see the javadoc comments. That's why declaring the throws clause could be useful.

Also it is easier for some programmers to quickly determine the exception from method signature than to see what is there inside javadoc.

But in general I think that it's more useful to list unchecked exceptions only in javadocs because if there are both checked and unchecked exceptions in throws clause the situation could be confusing. You cannot determine the type of exception without compiler or without looking into each exception class signature.

However unchecked exceptions mean that situation is critical and couldn't be fixed by the program at runtime. If you use unchecked exceptions by purpose of checked exceptions (you assume that situation could be fixed) but for some reason you don't want the compiler to force catching the exception then I recommend to put the exception inside throws clause too.