java - 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

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.