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

검사 예외(checked exception)은 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자. 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자.

throws Exception이나 Throwable을 하면 안된다. 사용자에게 각 예외에 대처할 수 있는 힌트도 못주고 다른 예외들까지 삼켜버릴 수 있다. main() 메서드는 오직 JVM만이 호출하므로 Exception을 던지도록 선언해도 괜찮다.

 

/**
 * @throws IllegalStateException
 */
public void testMethod(String parameter) throws IllegalStateException {
  
}

비검사 예외(unchecked exception)도 문서화해두면 좋다. public 메서드라면 필요한 전제조건들을 문서화해야 하며, 그 수단으로 가장 좋은 것이 비검사 예외들을 문서화하는 것이다.

 

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

 

하지만 비검사 예외도 모두 문서화하는 것이 현실적으로 불가능할 때도 있다. 외부 라이브러리 클래스가 이후 수정되어서 새로운 비검사 예외를 던지게 되어도 그 라이브러리를 가져다 쓰는 우리 메서드는 문서에 언급되지 않는 새로운 비검사 예외를 전파하게 될 것이다.

 

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

/**
 * @throws NullPointerException - 모든 메서드는 param에 null이 넘어오면 NullPointerExcetpion을 던진다.
 */
class Dummy throws NullPointerException {

   public void methodA(String param) {
       ...
   }

   public void methodB(String param) {
       ...
   }

   public void methodC(String param) {
       ...
   }
}