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

메서드가 던지는 예외를 모두 문서화하는 것이 좋습니다. 검사 예외는 항상 따로 선언하며, 예외가 발생하는 상황을 자바독의 @throws태그를 이용해 정확하게 문서화합니다.

이때 주의할 점은 아래와 같이 공통 상위 클래스 하나로 뭉뚱그려 선언하지 않는 것입니다.

/**
 * @throws Exception
 */
public void doSomething() throws Exception {
    // doSomething
}

이는 메서드 사용자에게 예외에 대처할 수 있는 힌트를 주지 못할뿐더러 같은 맥락에서 발생할 여지가 있는 다른 예외들 까지 삼켜버릴 수 있기 때문에 API 사용성을 크게 떨어뜨립니다.

비검사 예외도 문서화하면 좋습니다. 하지만 메서드 선언의 throws목록에는 넣지 않아야 합니다.

비검사 예외를 문서화하는 것이 불가능한 경우도 있습니다. 다른 사람이 작성한 외부 클래스를 사용하는 메서드의 경우 이 클래스가 수정되게 되면 우리가 작성한 메서드에는 문서화 되지 않은 새로운 비검사 예외가 전파되게 됩니다.