책/이펙티브 자바
item 74 메서드가 던지는 모든 예외를 문서화하라
함께자라기
2022. 4. 22. 17:29
ITEM 74 메서드가 던지는 모든 예외를 문서화하라
메서드가 던지는 예외는 그 메서드를 올바로 사용하는데 아주 중요한 정보니 예외 하나하나 모두 문서화 하는게 좋다
검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화 하자
- 공통 상위 클래스 하나로 뭉뚱그려 선언 하지 말자
- 극단적인 예) 메서드가 Exception, Throwable을 던진다고 선언하면 안된다
- 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못한다
- 같은 맥락에서 발생 가능한 다른 예외까지 삼켜 API 사용성을 떨어뜨린다
- 이 규칙의 유일한 예외는 오직 JVM만이 호출하는 main 메서드이다
자바 언어가 요구하지는 않지만 비검사 예외도 검사 예외처럼 문서화 해두면 좋다
- 비검사 예외는 보통 프로그래밍 오류를 하는데 자신이 일으킬 수 있는 오류가 뭔지 알려주면 개발자가 미연에 방지가 가능하다
- 잘 정비된 비검사 예외 문서는 사실상 그 메서드를 성공적으로 수행하기 위한 전제조건이 된다
- public 메서드면 필요한 전제조건을 문서화해야 하며 그 수단으로 가장 좋은게 비검사 예외를 문서화 하는 것
- 특히 인터페이스에서 비검사 예외 문서화가 중요한데 이 조건이 인터페이스의 일반 규약에 속해 인터페이스를 구현한 구현체 모두가 일관되게 동작하도록 해주기 때문
메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자
- 검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지니 이걸 구분하는게 좋다
- 자바독 유틸리티는 메서드 선언의 throws 절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해준다
- 따라서 개발자는 뭐가 비검사 예외인지 바로 알 수 있다
비검사 예외도 모두 문서화 하면 좋지만 현실적으로 불가능 한 경우도 있다
- 클래스를 수정하면서 새로운 비검사 예외를 던져도 소스 호환성과 바이너리 호환성이 유지 된다는게 가장 큰 이유다
- 만약 다른 사람이 작성한 클래스를 사용하는 메서드가 있고 발생 가능한 모든 비검사 예외를 문서화 했지만 이 외부 클래스가 다른 비검사 예외를 던지게 수정되면 아무 수정도 하지 않은 우리 메서드에서는 문서에 언급되지 않은 비검사 예외를 전파할 것이다
한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 그 예외를 각각의 메서드가 아닌 클래스 설명에 추가하는 방법도 있다
- NPE가 가장 흔한 사례이며 이럴때 클래스의 문서화 주석에 "이 클래스의 모든 메서드는 인수로 null이 넘어오면 NPE가 발생한다" 라고 써도 된다