티스토리 뷰
검사 예외든, 비검사 예외든, 추상 메서드든, 구체 메서드든
메서드가 던질 가능성이 있는 모든 예외를 문서화하라.
🐱👤 검사예외
검사 예외는 항상 따로따로 선언하고,
각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자.
만약, 공통 상위 클래스 하나로 예외를 뭉뚱그려 선언한다면
메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못할뿐더러,
같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있어 API 사용성을 크게 떨어뜨린다.
(하지만 오직 JVM만이 호출하는 main 메서드는 예외다. Exception을 던지도록 선언해도 괜찮음)
🐱💻 비검사예외
자바 언어가 요구하는 것은 아니지만, 비검사 예외도 검사 예외처럼 문서화해두면 도움이 된다.
잘 정비된 비검사 예외 문서는 그 메서드를 성공적으로 수행하기 위한 전제조건이 된다.
public메서드라면 필요한 전제조건을 문서화해야 하며, 그 수단으로 가장 좋은 것이 바로 비검사 예외들을 문서화하는 것이다.
특히 인터페이스 메서드에서 중요하다.
해당 예외 조건이 인터페이스의 일반 규약에 속하게 되어, 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문이다.
하지만 주의할 것은
메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되,
비검사 예외는 메서드 선언의 throws 목록에 넣지 말자.
자바독 유틸리티는 메서드 선언의 throws 절에 등장하고, 메서드 주석의 @throws 태그에도 명시한 예외와
@throws 태그에만 명시한 예외를 시각적으로 구분하여 검사냐 비검사냐에 따라 프로그래머가 바로 알 수 있도록 한다.
🐱👓 이 외의 처리
현실적으로 모든 예외를 문서화하는 것은 불가능할 수 있다.
예를 들어, 클래스와 발생 가능한 모든 예외를 공들여 문서화했다. 하지만 후에 외부 클래스가 새로운 비검사 예외를 던지게 된다면, 아무 수정도 하지 않은 우리 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 될 것이다.
한 클래스에 정의된 많은 메서드가 같은 이유로 예외를 던진다면
그 예외를 각각의 메서드가 아닌 클래스 설명에 추가하는 방법도 있다. (ex. NullPointerException)
💡 정리
- 메서드가 던질 가능성이 있는 모든 예외를 문서화하라.
- 검사 예외든 비검사 예외든, 추상 메서드든, 구체 메서드든 모두 마찬가지다.
- 문서화에는 자바독의 @throws 태그를 사용하면 된다.
- 검사 예외만 메서드 선언의 throws 문에 일일이 선언하고, 비검사 예외는 메서드 선언에는 기입하지 말자.
- 발생 가능한 예외를 문서로 남기지 않으면 다른 사람이 그 클래스나 인터페이스를 효과적으로 사용하기 어렵거나 심지어 불가능할 수도 있다.
'Programming > Effective Java' 카테고리의 다른 글
[이펙티브자바] Item 75. 예외의 상세 메시지에 실패 관련 정보를 담으라 (0) | 2022.08.23 |
---|---|
[이펙티브자바] Item 2. 생성자에 매개변수가 많다면 빌더를 고려하라 (0) | 2022.08.10 |
[이펙티브자바] Item 73. 추상화 수준에 맞는 예외를 던지라 (0) | 2022.08.07 |