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

메소드가 던지는 예외는 그 메서드를 올바로 사용하는 데 아주 중요한 정보다. 따라서 예외를 문서화하는 데 시간을 쏟아야 한다.

검사 예외

검사 예외는 항상 따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용해 문서화하자.
공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자. Exception이나 Throwable을 던진다고 선언해서는 안 된다. 예외에 대처할 수 있는 힌트를 주지 못할뿐더러, 다른 예외까지 삼켜버려 API 사용성을 크게 떨어뜨린다.

비검사 예외

자바 언어가 요구하는 것은 아니지만 비검사 예외도 문서화해두면 좋다. 비검사 예외는 일반적으로 프로그래밍 오류를 뜻하는데, 자신이 일으킬 수 있는 오류들이 무엇인지 알려주면 프로그래머는 자연스럽게 해당 오류가 나지 않도록 코딩하게 된다. 잘 정비된 비검사 예외 문서는 사실상 그 메서드를 성공적으로 수행하기 위한 전제조건이 된다.

메서드가 던질 수 있는 예외를 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자. 검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분해주는게 좋다.

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