Question

Joshua Bloch in his Effective Java writes :

“Use the Javadoc @throws tag to document each unchecked exception that
a method can throw, but do not use the throws keyword to include unchecked
exceptions in the method declaration. “

Well that sounds reasonable indeed, but how to find out, what unchecked exception can my method throw?

Let’s think of a following class :

public class FooClass {

    private MyClass[] myClass;

    /**
     * Creates new FooClass
     */
    public FooClass() { 
        // code omitted
        // do something with myClass
    }

    /**
     * Performs foo operation.<br />
     * Whatever is calculated.
     * @param index Index of a desired element
     * @throws HorribleException When something horrible happens during computation
     */
    public void foo(int index) {
        try {
            myClass[index].doComputation();
        } catch (MyComputationException e) {
            System.out.println("Something horrible happened during computation");
            throw new HorribleException(e);
        }
    }
}

Now, I documented HorribleException, but it is quite obvious, that foo method can also throw unchecked java.lang.ArrayIndexOutOfBoundsException. The more complex the code gets, it’s harder to think of all unchecked exceptions that method can throw. My IDE doesn’t help me much there and nor does any tool. Since I don’t know any tool for this …

How do you deal with this kind of situation?

Answer 1

Only document those which you’re explicitly throwing yourself or are passing through from another method. The remnant is to be accounted as bugs which are to be fixed by good unit testing and writing solid code.

In this particular case, I’d account ArrayIndexOutOfBoundsException as a bug in your code and I’d fix the code accordingly that it never throws it. I.e. add a check if the array index is in range and handle accordingly by either throwing an exception -which you document- or taking an alternative path.