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

[yejin9858]

메서드가 던지는 예외는 그 메서드를 올바로 사용하는 데 아주 중요한 정보다.

따라서 메서드를 자세히 문서화하는데 충분한 시간을 쏟자(Item 56 참고)

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

• 공통 상위 클래스 하나로 뭉뚱그려 선언 X

  • 메서드가 Exception이나 Throwable을 던진다고 선언하지 말고, 어떤 예외를 던지는지 정확히 알려주자.

  • 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지도 못할 뿐더러, 같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있어 API 사용성을 크게 떨어뜨림.

    // 잘못 사용한 예
    public void method() throws Exception {
    
    }
    
    // or
    
    public void method() throws Throwable {
    
    }
    
    // 올바르게 사용한 예
    /**
     * @throws IllegalStateException
     */
    public void method(String parameter) throws IllegalStateException {
      
    }
    
    /**
     *
     * @throws IllegalStateException
     * @throws SQLException
     * @throws NumberFormatException - params가 숫자형 데이터가 아닌경우 throw
     */
    public void method(String params) throws IllegalStateException, SQLException, NumberFormatException {
      
    }

  • 예외) main은 JVM만이 호출하므로 Exception을 던진다고 선언해도 괜찮다.

• 비검사 예외(프로그래밍 예외)도 검사예외처럼 정성껏 문서화해두면 좋다.(Item 70 참고)
  • 프로그래머는 자연스레 해당 오류들이 나지 않도록 코딩하게 되며 잘 정비된 비검사 예외는 사실상 그 메서드를 성공적으로 수행하기 위한 전제조건이 된다.
  • 이런 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 작동하도록 해준다.

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

• 검사나 비검사에 따라 API 사용자가 해야할 일이 달라지므로 이 둘을 확실히 구분해주는게 좋다.
  • 자바독 유틸리티는 메서드 선언의 throws 절에 등장
  • 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해준다.
• 비검사 예외도 문서화하라고 했지만 현실적으로 불가능할 때도 있다.
  • 클래스를 수정하면서 새로운 비검사 예외를 던지게 되어도 소스 호환성과 바이너리 호환성은 그대로 유지된다.
  • 예를 들어 다른 사람이 작성한 메서드를 사용하는데 발생 가능한 모든 예외를 공들여 문서화했는데, 후에 이 외부 클래스가 새로운 비검사 예외를 던지게 수정된다면?
    • 우리 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 됨

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

ex) NullPointException

이 클래스의 모든 메서드는 인수로 null이 넘어오면 NullPointerException을 던진다. 라고 적어도 좋다.