핵심 요약
- 검사 예외는 반드시 문서화해야 한다
- 자바독의 @throws 태그와 메소드 선언의 throws를 선언하자.
- 비검사 예외도 웬만하면 문서화하자.
- 자바독의 @throws 태그만 사용하면 된다.
검사 예외
: 검사 예외는 반드시 문서화해야 한다.
- 메소드가 던지는 검사 예외 각각은 @throws 태그를 사용하여 문서화해야 한다.
- 상위 예외 클래스(ex. Exception, Throwable)로 선언하지 말자.
- 어떤 구체적인 예외 상황이 발생할 수 있는지 파악하기 어려워진다.
- 또한, 예상치 못한 다른 예외들까지 포괄적으로 처리할 수 있다. 따라서 예외 처리가 모호해지며, 이로 인해 발생하는 버그나 문제를 찾기 어려워진다.
- main 메소드는 예외이다.
- main 메소드 내에서 Exception을 던지도록 선언하는 것은 허용된다.
- 그 이유는 이러한 예외는 JVM에 의해 처리되고, 개발자가 직접 처리할 필요가 없기 때문이다.
비검사 예외
: 비검사 예외도 문서화하는 것이 좋다. (웬만하면 다 하자)
- 비검사 예외를 문서화하면, 해당 메소드를 사용하는 개발자는 해당 예외를 인지하고 그에 따라 적절하게 코드를 작성하게 된다.
- 즉, 해당 메소드를 올바르게 사용하기 위한 조건을 제공하는 방법이다.
- 공개 API인 public 메소드는 문서화하는 것이 더욱 중요하다.
- 특히, 인터페이스 메소드에 문서화하는 것은 중요하다.
- 인터페이스는 여러 구현체를 가질 수 있다.
- 인터페이스의 메소드에 발생 가능한 예외를 문서화하면, 그 인터페이스를 구현한 클래스들이 동일한 예외 조건을 따르도록 강요된다.
- 이로 인해 인터페이스를 구현한 모든 구현체가 일관된 방식으로 동작하게 된다.
검사 예외 vs 비검사 예외
✍ 메소드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메소드 선언의 throws 목록에 넣지 말자.
- 비검사 예외는 호출자에게 처리를 강제하지 않으므로 @throws 태그로만 문서화할 수 있다.
- 자바독을 생성할 때 throws 절에 선언된 예외와 @throws 태그에만 명시된 예외는 별도로 표시된다.
- 따라서 검사 예외와 비검사 예외를 명확하게 구분할 수 있다.
/**
* @throws IllegalArgumentException if the input is negative.
*/
public void sampleMethod(int input) {
if (input < 0) {
throw new IllegalArgumentException("Input should not be negative.");
}
}
✍ 가능한 한 비검사 예외도 문서화하고, 외부 의존성을 업데이트할 때는 주의해서 수행하라.
- 외부 라이브러리나 프레임워크는 새 버전에서 새로운 비검사 예외가 추가될 수 있다.
- 반면 내가 작성한 코드는 그대로라면, 라이브러리를 업데이트하면서 새로운 비검사 예외가 발생하게 된다.
- 즉, 예기치 않은 런타임 오류를 초래할 수 있다.
✍ 한 클래스에 정의된 많은 메소드가 같은 이유로 같은 예외를 던진다면 그 예외를 각각의 메소드가 아닌 클래스 설명에 추가하는 방법도 있다.
예시 3
/**
* 이 클래스의 모든 메소드는 인수로 null이 넘어오면 NullPointerException을 던진다.
*/
public class SampleClass {
public void method1(Object obj) {
if (obj == null) {
throw new NullPointerException();
}
// ... 메소드 내용 ...
}
public void method2(Object obj) {
if (obj == null) {
throw new NullPointerException();
}
// ... 메소드 내용 ...
}
// ... 더 많은 메소드들 ...
}
- 각 메소드마다 같은 예외에 대해 주석을 작성하는 것보다는 클래스 전체의 주석에 한 번만 기록하는 것이 중복을 줄이고 문서화를 깔끔하게 할 수 있다.
