Skip to main content

Exception Documentation and Handling

Source: Effective Java, 3rd Edition — Chapter 10 by Joshua Bloch (Items 74–77)

This lesson closes Chapter 10: documenting thrown exceptions, rich detail messages, failure atomicity, and why empty catch blocks are dangerous.

Item 74: Document all exceptions thrown by each method​

Document every exception a method can throw — checked and unchecked — with @throws in Javadoc (Item 56). Unchecked exceptions describe preconditions; unchecked docs are especially important on interfaces.

Rules:

  • Declare each checked exception individually in the method’s throws clause — never throws Exception or throws Throwable (except main).
  • Document unchecked exceptions with @throws only — do not list them in throws (that visual distinction matters).
  • Class-level docs can cover repeated cases (e.g. “all methods throw NullPointerException on null args”).
Quiz

Documenting exceptions

1 / 2

public void foo() throws Exception

Pick an answer to see if you are right.

Item 75: Include failure-capture information in detail messages​

When something fails in production, the stack trace’s detail message may be the only clue. Include parameter and field values that contributed to the failure:

throw new IndexOutOfBoundsException(
    "Index: " + index + ", Size: " + size);

Prefer exception constructors that take structured data and build the message centrally — and expose accessors on checked exceptions for recovery logic. Don’t put secrets (passwords, keys) in messages.

Detail messages are for engineers, not end-user UI copy.

Item 76: Strive for failure atomicity​

After a method throws, the object should usually remain usable — in the same state as before the call (failure-atomic).

Techniques:

  1. Immutable objects — failure atomicity is free.
  2. Validate before mutate — check preconditions first (Stack.pop checks size == 0 before --size).
  3. Compute-then-commit — do risky work on a copy, swap in on success.
  4. Recovery/rollback — rare; mainly for durable structures.

Document when atomicity cannot be guaranteed (e.g. after ConcurrentModificationException).

Quiz

Failure atomicity

1 / 2

Stack.pop decrements size before checking empty

Pick an answer to see if you are right.

Item 77: Don’t ignore exceptions​

An empty catch block silences failures and makes debugging nightmares — the program may fail later, far from the root cause.

// Don't
try {
    ...
} catch (SomeException e) {
}

// Rare OK: comment why, name variable ignored
} catch (IOException ignored) {
    // already read everything needed; close failure is harmless
}

Prefer handling, propagating, or logging. Applies to checked and unchecked exceptions.

Items 74–77 map​

ItemMove
74@throws every exception; throws only checked
75Detail messages capture failing parameter values
76Validate before mutate; object usable after failure
77Never empty catch; propagate, handle, or log

Chapter 10 complete. Next: Concurrency (Chapter 11, Items 78–81).