Item74. 메서드가 던지는 모든 예외를 문서화하라!
Intro
- 메서드가 던지는 예외는 올바른 메서드 사용에 아주 중요한 정보다.
- 따라서 각 메서드가 던지는 예외 하나하나를 문서화하는 데 충분한 시간을 쏟아야 한다.
조언
- 검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자.
- 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일을 삼가자.
- 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 줄 수 있어야 한다.
- 이 규칙에서 유일한 예외는 main 메서드로, main은 오직 JVM만이 호출하므로 Exception을 던져도 된다.
자바 언어가 요구하는 것은 아니지만 비검사 예외도 검사 예외처럼 문서화해두면 좋다.
- 비검사 예외는 일반적으로 프로그래밍 오류를 말한다.
- 자신이 일으킬 수 있는 오류들이 무엇인지 알려주면 프로그래머는 자연스레 해당 오류가 나타나지 않게 코딩하게 된다.
- 잘 정비된 비검사 예외 문서는 사실상 그 메서드를 성공적으로 수행시키는 전제조건이 된다.
- public 메서드라면 필요 전제조건을 문서화해야 하고, 그 수단으로 가장 좋은 것이 비검사 예외 문서화다.
- 발생 가능한 비검사 예외를 문서로 남기는 일은 인터페이스 메서드에서 특히 중요하다.
- 이 조건이 인터페이스의 일반 규약에 속하게 되어 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 한다.
- 비검사 예외도 모두 문서화하라고는 했지만 현실적으로 불가능할 때도 있다.
- 클래스를 수정하면서 새로운 비검사 예외를 던지게 되어도, 소스나 바이너리 호환성은 그대로 유지된다.
- 예를 들어 외부 클래스를 사용하는 메서드가 있다 가정해보자. 메서드 작성 시 발생 가능한 모든 예외를 공들여 문서화했다. 하지만 후에 외부 클래스가 수정되어 새로운 비검사 예외를 던지게 되었다면, 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 던지게 된다.
메서드가 던질 수 있는 예외 각각을 @throws 태그로 문서화하되, 비검사 예외는 선언의 @throws 목록에 넣지 말자.
- 검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지니, 구분이 필요하다.
- 자바독 유틸리티는 메서드 선언의 throws 절에 등장한다. 메서드 주석의 @throws 주석에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해준다.
- 위 구분을 이용해, 비검사 예외를 메서드 선언의 throws 목록에 넣지 않음으로써 어느 것이 비검사 예외인지 바로 알 수 있도록 하자.
한 클래스에 정의된 많은 메서드가 같은 이유로 예외를 던지는 경우, 그 예외를 클래스 설명에 추가하는 방법도 있다.
NullPointerException이 가장 대표적인 예다.- 각각의 메서드가 인수로 null을 받으면 NullPointerException을 던진다면, 각각의 메서드가 아닌 클래스 설명에 이러한 내용을 추가해 설명할 수 있다.
핵심 정리
- 메서드가 던질 가능성이 있는 모든 예외를 문서화하라.
- 검사 예외, 비검사 예외, 추상 메서드, 구체 메서드 모두 마찬가지다.
- 문서화에는 자바독의 @throws 태그를 사용하면 된다.
- 검사 예외만 메서드 선언의 throws 문에 일일이 선언하고, 비검사 예외는 메서드 선언에는 기입하지 말자.
Comments powered by Disqus.