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

Effective Java 3e item 74 메서드가 던지는 모든 예외를 문서화하라를 요약한 내용입니다.

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

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

공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자.

극단적인 예로 메서드가 최상위 예외인 Exception과 Throwable을 던진다고 해서는 안된다.

main 메서드는 JVM만이 호출하기 때문에 예외이다.

비검사 예외도 검사 예외처럼 정성껏 문서화 해두면 좋다.

1. 비검사 예외는 일반적으로 프로그래밍 오류를 뜻하는데, 자신이 일으킬 수 있는 오유들이 무엇인지 알려주면 프로그래머는 자연스럽게 오류가 나지 않는 쪽으로 코딩을 하게 된다.
2. public 메소드라면 필요한 전제조건을 문서화 해야하며 그 수단으로 가장 좋은 것이 바로 비검사 예외들을 문서화하는 것이다.
3. 발생 가능한 비검사 예외를 문서로 남기는 일은 인터페이스 메서드에서 특히 중요하다.

   이 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문이다.

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

검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분해주는게 좋다.

자바독 유틸리티는 메서드 선언의 throws절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws태그에만 명시한 예외를 시각적으로 구분해준다. >?

   /**
     *
     * @return secondField
     * @throws NullPointerException if parameter is null or empty 비검사예외
     * @throws IllegalAccessError if someone access 검사예외
     */
    public int getSecondField() throws IllegalAccessError {
        return secondField;
    }

비검사 예외도 모두 문서화하라고는 했지만 현실적으로 불가능할때도 있다.

클래스를 수정하면서 새로운 비검사 예외를 던지게 되어도 소스 호환성과 바이너리 호환성이 그대로 유지된다는게 큰 이유다.

외부 클래스를 사용할 경우, 비검사 예외를 모두 문서화 했다 해도 외부 클래스가 새로운 비검사 예외를 던지게 수정된다면 아무 수정도 하지 않은 우리 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 된다.

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

예를 들어 많은 메서드가 NullPointerException 을 던진다면 클래스 상단 주석에 '이 클래스의 모든 메서드는 인수로 null이 넘어오면 NullPointerException 을 던진다' 라고 쓰는 식이다.

핵심정리

메서드가 던질 가능성이 있는 모든 예외를 문서화하라. 이는 검사예외, 비검사예외 추상메서드, 구체메서드 모두 마찬가지이다. 자바독의 @throws 태그를 이용하자. 검사 예외만 메서드의 throws 문에 일일히 선언하고 비검사예괴는 메서드에 직접 기입하지 말자. 예외를 문서로 남기지 않으면 다른 사람이 그 클래스나 인터페이스를 효과적으로 사용하기 어렵거나 심지어 불가능할 수도 있다.