[이펙티브 자바] item 74 - 메서드가 던지는 모든 예외를 문서화하라

■검사 예외 문서화의 중요성

검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를

사용하여 정확히 문서화하자. Exception, Throwable같은 공통 상위 예외로 퉁치지는 말자.

왜냐하면 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못한다. 또한 같은 

맥락에서 발생할 여지가 있는 다른 예외들까지 포함시켜버릴 수 있어 API 사용성을 크게 

떨어뜨린다. 

main 메서드는 이 규칙에 유일한 예외이다. 

main은 오직 JVM만이 호출하므로 Exception을 던지도록 선언해도 괜찮다.

■비검사 예외 문서화의 중요성

자바 언어가 요구하는 것은 아니지만 비검사 예외도 문서화해두면 좋다. 비검사 예외는 

일반적으로 프로그래밍 오류를 뜻하는데 (item 79), 자신이 일으킬 수 있는 오류들이

무엇인지 알려주면 프로그래머는 자연스럽게 해당 오류가 나지 않도록 코딩하게 된다.

잘 정비된 비검사 예외 문서는 사실상 그 메서드를 성공적으로 수행하기 위한 전제조건이 

된다. public 메서드라면 필요한 전제조건을 문서화해야 하며(item 56) 그 수단으로 가장 

좋은 것이 바로 비검사 예외들을 문서화하는 것이다.

발생 가능한 비검사 예외를 문서로 남기는 일은 인터페이스 메서드에서 특히 중요하다.

이 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가

일관되게 동작하도록 해주기 때문이다.

---

메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 

선언의 throws 목록에 넣지 말자. 검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 

달라지므로 이 둘을 확실히 구분해주는 게 좋다. 자바독 유틸리티는 메서드 선언의 throws 

절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 

예외를 시각적으로 구분해준다. 그래서 프로그래머는 어느 것이 비검사 예외인지를 바로 알 

수 있다.

---

비검사 예외도 모두 문서화하라고는 했지만 현실적으로 불가능할 때도 있다. 클래스를 

수정하면서 새로운 비검사 예외를 던지게 되어도 소스 호환성과 바이너리 호환성이 그대로

유지된다는 게 가장 큰 이유다. 예컨대 다른 사람이 작성한 클래스를 사용하는 메서드가 

있다고 해보자. 그리고 발생 가능한 모든 예외를 공들여 문서화했다. 하지만 후에 이 외부 

클래스가 새로운 비검사 예외를 던지게 수정된다면, 아무 수정도 하지 않은 우리 메서드는

문서에 언급되지 않은 새로운 비검사 예외를 전파하게 될 것이다.

---

한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면, 그 예외를 각각의 

메서드 레벨의 설명이 아닌 클래스 레벨의 설명에 추가하는 방법도 있다. (ex NPE)