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

💥 개요

메서드가 던지는 예외는 그 메서드를 올바로 사용하는 데 아주 중요한 정보다. 따라서 문서화에 충분히 신경써야 한다.

검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용해 정확히 문서화해야 한다. 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자. 극단적인 예로 메서드가 Exception이나 Throwable을 던진다고 선언해서는 안 된다. 힌트도 주지 못하고 다른 예외까지 삼켜버릴 수 있어 API 사용성을 크게 떨어뜨린다.(main 메서드 제외함. JVM만이 호출하므로 괜찮다.)

 

🕹️ 비검사 에외도 문서화하자

자바 언어가 요구하는 것은 아니지만 비검사 예외도 정성껏 문서화하면 좋다. 일반적으로 프로그래밍 오류를 비검사 예외라고 말하는데, 자신이 일으킬 수 있는 오류들이 무엇인지 알려주면 개발자는 자연스레 해당 오류가 나지 않도록 코딩하게 된다.

잘 작성한 문서는 사실상 그 메서드를 성공적으로 수행하기 위한 전제조건이 된다. public 메서드면 필요한 전제조건을 문서화해야 하며 그 수단으로 가장 좋은 것이 비검사 예외를 문서화하는것이다.

하지만 메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 thorws 목록에 넣지 말자. 검사냐 비검사냐에 따라 사용자가 해야 할 일이 다르기 때문에 구분하는게 좋다.

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

 

가장 대표적인 사례

이럴 때는 클래스 문서화 주석에 "이클래스의 모든 메서드는 null이 넘어오면 NPE를 던진다. 라고 적어도 좋다ㅣ.

 

메서드가 던질 가능성이 있는 모든 예외를 문서화하라.
검사/비검사 예외, 추상/구체 메서드 모두에 해당한다.
문서화에는 자바독의 @throws 태그를 사용하고,
검사 예외만 메서드 선언의 throws 문에 일일히 선언한다.