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

메서드가 던지는 예외는 해당 메서드를 올바르게 사용하기 위한 중요 정보이다. 따라서, 모든 예외를 문서화하는 것이 좋다.

예외 문서화 지침

검사 예외는 항상 각자 따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 이용하여 정확히 문서화하자.

검사 예외를 공통 상위 클래스 하나로 뭉뚱그려 선언하는 것은 좋지 않다. 극단적인 예시로, 메서드가 최상위 클래스 Exception 나 Throwable 을 던지게 하면 안된다.

이는 메서드 사용자들에게 충분한 대처법을 제공하지 못하고, 다른 예외까지 삼킬 수 있어서 API 사용성을 크게 떨어트리기 때문이다.

비검사 예외의 문서화는 프로그래머 입장에서 중요하다. 비검사 예외가 뜨는 상황은 보통 프로그래밍 오류를 뜻하므로, 프로그래머가 일으킬 수 있는 오류가 무엇인지 잘 설명되어 있으면 자연스럽게 해당 오류를 방지할 수 있다.

잘 정비된 비검사 예외 문서는 해당 메서드를 성공적으로 수행하기 위한 전제조건이 된다. public 메서드라면 필요한 전제 조건을 문서화해야 하며 이를 구체적으로 제공하기 위한 수단으로 비검사 예외 문서화를 사용할 수 있다.

특히, 비검사 예외의 문서화는 인터페이스 메서드에서 중요하다. 이 조건들이 인터페이스의 일반 규약에 속하게 되어, 인터페이스를 구현한 모든 구현체가 일관된 동작을 하도록 만들어주기 때문이다.

이런 비검사 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말아야한다. (검사 예외와 비검사 예외의 명확한 구분을 위해서)

한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던질수도 있다. 이 때는 공통 클래스 설명에 예외를 설명해줄 수도 있다. (ex. NullPointerException)

예를 들어, 클래스 문서화 주석에 "해당 클래스의 모든 메서드는 인수로 null 넘어오면 NullPointerException 을 던진다." 명시