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

[chikeem90]

핵심 정리

• 메서드가 던질 가능성이 있는 모든 예외를 문서화하라. (검사 예외 / 비검사 예외 모두)
• 메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자.
  • 자바독 유틸리티는 메서드 선언의 throws 절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해주므로, 프로그래머는 어느 것이 비검사 예외인지 바로 알 수 있음.

@Repository
public class CartProductRepository {
    /**
     * cartProductId를 받아서 조회하는 메서드
     * @param cartProductId 장바구니ID
     * @return CartProduct를 반환
     * @throws IllegalArgumentException cartProductId가 null인 경우 발생
     */
    public CartProduct findCartProductFromDb(String cartProductId) {
        if (cartProductId == null) {
            throw new IllegalArgumentException();
        }
        return new CartProduct(cartProductId);
    }

    /**
     * 파일로부터 cartProduct 정보를 읽어서 반환하는 메서드
     * @param filePath 읽을 파일 경로
     * @return CartProduct를 반환
     * @throws IOException file이 없는 경우 발생
     */
    public CartProduct findCartProductFromFile(String filePath) throws IOException {
        File file = new File(filePath);
        String cartProductId;
        try (BufferedReader br = new BufferedReader(new FileReader(file))) {
            cartProductId = br.readLine();
        }
        return new CartProduct(cartProductId);
    }
}

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

참고

• @throws가 있고 @exception도 있는데 서로 동의어
• https://stackoverflow.com/questions/5510170/in-javadoc-what-is-the-difference-between-the-tags-throws-and-exception

[corock]

몰랐던 점을 많이 볼 수 있었네요~ 잘 읽었습니다.

1. unchecked exception 은 @throws 목록에 넣지 않는 것과
2. @exception Javadoc 도 있다는 점

[corock]

1번은 메서드 시그니처 옆 throws 를 말하는 거였군요