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

검사 예외의 문서화

---

검사 예외는 (RuntimeException 및 Error를 제외한 예외들) 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 통하여 정확히 문서화하자.

 

극단적인 예로 메서드가 Exception이나 Throwable을 던진다고 선언해서는 안된다. 이렇게 선언해버리면 API 사용성을 크게 떨어트릴 수 있다. (상세 예외 케이스를 내어주지 못하니 대처가 힘듦)

 

위 규칙에는 예외가 있는데 바로 main 메서드이다. JVM에서만 호출하므로 Exception을 던져도 무방하다.

 

비검사 예외의 문서화

---

비검사 예외도 정성껏 문서화하면 좋다. 프로그래밍을 하면서 나는 프로그래밍 오류들이 비검사예외인데 이러한 상황을 맞딱트릴 수 있다고 API에서 먼저 문서화 해두면 코딩 할 때 주의 할 수 있다.

 

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

 

/**
 * 매장 안의 모든 치즈 목록을 반환한다.
 *
 * @return 치즈 목록
 * @throws IllegalStateException 만약 재고가 null인 경우 발생
 * @throws RuntimeException 비검사 예외 예제
 */
public List<Cheese> getCheeses() throws IllegalStateException{
    if (cheesesInStock == null) {
        throw new NullPointerException("재고가 null입니다.");
    }

    return cheesesInStock.isEmpty() ? null : new ArrayList<>(cheesesInStock);
}

자바독 유틸리티는 메서드 선언부에 throw 절에 등장하고 @throws에 명시한 예외와 @throws에만 명시한 예외의 시각적인 처리를 달리해줘서 비검사 예외와 검사 예외를 구분하여 볼 수 있다.

 

그리고, 한 클래스 내부에서 동일한 이유로 같은 예외를 던지면 그 예외를 클래스 설명에 추가하는 방법도 존재한다.