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

예외 문서화의 중요성

메서드가 던지는 예외는 그 메서드를 올바로 사용하는 데 있어 매우 중요한 정보다. 따라서 각 메서드가 던질 수 있는 예외를 충분히 문서화하는 데 시간을 들이는 것이 필요하다. 특히 공용 API를 작성할 때는, 예외의 의미와 발생 조건을 명확히 전달해야 한다.

1. 예외 문서화의 필요성

1) 검사 예외와 비검사 예외의 차이

검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독(JavaDoc)의 @throws 태그를 사용해 정확히 문서화하자. 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가는 것이 좋다. 예를 들어, 메서드가 Exception이나 Throwable을 던진다고 선언해서는 안 된다. 이러한 선언은 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 제공하지 못할 뿐만 아니라, 같은 맥락에서 발생할 수 있는 다른 예외들까지 삼켜버리게 된다. 이는 API 사용성을 크게 저하시킬 수 있다.

예외: main 메서드의 경우에는 Exception을 던지도록 선언해도 괜찮다. 왜냐하면 main 메서드는 오직 JVM에 의해서만 호출되기 때문이다.

자바 언어가 요구하는 것은 아니지만, 비검사 예외도 검사 예외처럼 정성껏 문서화해두는 것이 좋다. 비검사 예외는 일반적으로 프로그래밍 오류를 나타내므로, 이러한 오류들을 문서화해두면 개발자가 자연스럽게 오류가 발생하지 않도록 코딩하게 된다. 잘 문서화된 비검사 예외는 사실상 그 메서드를 성공적으로 수행하기 위한 전제 조건이 된다.

2) 예외 문서화의 예시

다음은 메서드에서 발생 가능한 예외를 자바독으로 문서화하는 예시이다.

/**
 * 이 메서드는 지정된 파일을 열고 내용을 읽어 반환합니다.
 *
 * @param filePath 읽을 파일의 경로
 * @return 파일 내용
 * @throws IOException 파일을 읽는 도중 문제가 발생한 경우
 * @throws NullPointerException filePath가 null인 경우
 */
public String readFile(String filePath) throws IOException {
    if (filePath == null) {
        throw new NullPointerException("파일 경로는 null일 수 없습니다.");
    }
    // 파일 읽기 로직
}

위 코드에서 @throws 태그를 사용해 검사 예외(IOException)와 비검사 예외(NullPointerException)의 발생 조건을 명확하게 문서화했다. 이렇게 문서화된 예외 정보는 메서드를 올바르게 사용하는 데 필요한 중요한 정보를 제공한다.

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

1) 비검사 예외도 문서화해야 하는 이유

비검사 예외는 메서드 선언의 throws 목록에 포함되지 않지만, 문서화는 반드시 필요하다. 비검사 예외는 주로 프로그래밍 오류를 의미한다. 예를 들어, NullPointerException이나 IllegalArgumentException과 같은 예외는 사용자가 잘못된 입력을 제공했거나, 전제 조건을 만족하지 못했을 때 발생한다.

부가 설명: 비검사 예외를 문서화하면 개발자가 해당 메서드를 사용할 때 발생 가능한 오류를 사전에 인지하고, 코드 작성 시 오류를 예방할 수 있다. 또한, 비검사 예외의 명확한 문서화는 API의 신뢰성을 높이고, 다른 개발자들이 코드를 보다 쉽게 이해하고 사용할 수 있도록 돕는다.

2) 인터페이스 메서드의 비검사 예외 문서화

발생 가능한 비검사 예외를 문서화하는 일은 특히 인터페이스 메서드에서 중요하다. 이러한 조건들이 인터페이스의 일반 규약에 포함됨으로써, 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 한다. 이는 인터페이스의 일관성을 보장하고, 사용자에게 예측 가능한 결과를 제공한다.

3. 예외 선언 시 고려 사항

1) 검사 예외와 비검사 예외의 구분

메서드가 던질 수 있는 예외는 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 포함하지 말자. 검사 예외와 비검사 예외는 발생하는 상황이 다르고, 이에 따라 API 사용자가 해야 할 일도 달라진다. 자바독(JavaDoc) 유틸리티는 메서드 선언의 throws 절에 등장한 예외와 @throws 태그로 문서화된 예외를 시각적으로 구분해준다. 이를 통해 프로그래머는 어떤 예외가 비검사 예외인지 바로 알 수 있다.

2) 비검사 예외 문서화의 현실적 한계

모든 비검사 예외를 문서화하는 것은 현실적으로 불가능할 때도 있다. 클래스가 수정되면서 새로운 비검사 예외를 던지게 되어도 소스 호환성과 바이너리 호환성이 그대로 유지된다는 점이 그 이유다. 예를 들어, 외부에서 제공된 클래스를 사용하는 메서드가 있다고 하자. 이 메서드는 발생 가능한 모든 예외를 공들여 문서화했다. 하지만 외부 클래스가 수정되어 새로운 비검사 예외를 던지게 되면, 이 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 될 것이다.

부가 설명: 따라서 모든 비검사 예외를 일일이 문서화하는 것은 어려울 수 있으며, 상황에 따라 유연하게 접근해야 한다. 그러나 가능한 한 비검사 예외를 문서화함으로써, 사용자에게 메서드 사용 시 발생 가능한 위험을 명확히 알려주는 것이 중요하다.

4. 클래스 단위 예외 문서화

클래스 수준의 예외 문서화

한 클래스에 정의된 여러 메서드가 동일한 이유로 같은 예외를 던질 수 있다면, 이를 각각의 메서드가 아닌 클래스 설명에 추가하는 방법도 있다. 예를 들어, 대부분의 메서드가 NullPointerException을 던질 수 있다면, 클래스 문서화 주석에 다음과 같이 설명할 수 있다.

"이 클래스의 모든 메서드는 인수로 null이 전달되면 NullPointerException을 던진다."

이렇게 하면 코드의 중복을 줄이고, 클래스의 사용자가 해당 클래스의 모든 메서드에 대해 일관된 예외 처리 규칙을 쉽게 이해할 수 있도록 돕는다.

💡 핵심 정리

• 메서드가 던질 가능성이 있는 모든 예외를 문서화하라. 검사 예외든 비검사 예외든, 추상 메서드든 구체 메서드든 모두 마찬가지다.

• 검사 예외는 메서드 선언의 throws 절에 반드시 포함하고, 비검사 예외는 선언에 포함하지 않지만 @throws 태그를 사용해 문서화하자.

• 발생 가능한 예외를 문서로 남기지 않으면, 다른 사람이 해당 클래스나 인터페이스를 효과적으로 사용하기 어렵거나 심지어 불가능할 수도 있다.

• 비검사 예외를 문서화함으로써 API의 신뢰성을 높이고, 사용자에게 명확한 사용 가이드라인을 제공할 수 있다.

올바른 예외 문서화는 프로그램의 안정성을 높이고, API 사용성을 극대화하는 중요한 요소다. 이를 통해 개발자들이 메서드를 안전하게 사용하고, 예상치 못한 오류를 피할 수 있도록 돕는 것이 중요하다.