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

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.