[Effective Java] 74.메서드가 던지는 모든 예외를 문서화하라

예외 문서화

메서드가 던지는 예외는 그 메서드를 올바르게 사용하기 위한 중요한 정보이므로 예외 하나하나를 문서화하는 데 충분한 시간을 쏟아야한다. [아이템 56]

• 검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자.
• 공통 상위 클래스 하나로 예외를 던지는 것을 삼가자. ex)Exception, Throwable (main 메서드만 예외)
• 비검사 예외도 검사 예외처럼 정성껏 문서화해두면 좋음 → 그 메서드를 성공적으로 수행하기 위한 전제조건이 됨
• 메서드가 던질 수 있는 예외를 @throws 로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자. (검사냐 비검사냐에 따라 API 사용자가 할 일이 달라지므로 확실히 구분하자)

/**
 * @throws SQLException SQL 이 잘못된 경우
 * @throws ClassNotFoundException 지정한 경로에 클래스파일이 존재하지 않는경우.
 * @throws NullPointerException 지정한 요소에 null 이 들어오는 경우
 */
public void example() throws SQLException,ClassNotFoundException {
    Class.forName("example");
    // TODO 무언가 했음.
}

• 한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 그 예외를 각각의 메서드가 아닌 클래스 설명에 추가해도 좋다.

 

결론

• 메서드가 던질 가능성이 있는 모든 예외를 문서화하라. (자바독의 @throws 태그 사용)
• 검사 예외만 메서드 선언의 throws 문에 일일이 선언하고, 비검사 예외는 선언하지 말자.
• 예외 문서화 → 사용자가 그 클래스나 인터페이스를 효과적으로 사용할 수 있다.