Effective Java ( 이펙티브 자바 )

메서드가 던지는 모든 예외를 문서화하라

메서드가 던지는 예외는 그 메서드를 올바로 사용하는 데 아주 중요한 정보다. 따라서 예외 하나하나를 문서화하는 데 충분한 시간을 쏟아야 한다.

검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자. 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자(Exception, Throwable).

이 규칙에 유일한 예외가 있다면 바로 main 메서드다. main은 오직 JVM만이 호출하므로 Exception을 던지도록 선언해도 괜찮다.

자바 언어가 요구하는 것은 아니지만 비검사 예외도 정성껏 문서화해두면 좋다. 일반적으로 프로그래밍 오류를 뜻하는데, 프로그래머가 자연스럽게 해당 오류가 나지 않도록 코딩하게 해준다.

메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자.

비검사냐 검사냐에 따라 사용자가 해야 할 일이 달라지므로 구분해주는 게 좋다. 하지만 비검사 예외는 현실적으로 모두 문서화가 불가능할 때도 있다. 소스 호환성과 바이너리 호환성이 그대로 유지된다는 게 가장 큰 이유다.

한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 그 예외를 클래스 설명에 추가하는 방법도 있다.

메서드가 던질 가능성이 있는 모든 예외를 문서화하라. 검사, 비검사, 추상, 구체메서드 모두. 검사 예외만 메서드 선언의 throws 문에 일일이 선언하고, 비검사 예외는 기입하지 말자.