아이템 74. 메소드가 던지는 모든 예외를 문서화하라. - ksw6169/effective-java GitHub Wiki
메소드가 던지는 모든 예외를 문서화하라.
- 메소드가 던지는 예외는 그 메소드를 올바로 사용하는 데 아주 중요한 정보다.
- 따라서 각 메소드가 던지는 예외 하나하나를 문서화하는 데 충분한 시간을 쏟아야 한다.
검사 예외는 항상 따로따로 선언하라.
- 검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을
@throws 태그를 사용해 문서화하자.
- 이 때 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자.
- 이는 메소드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못한다.
- 또한 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있어 API 사용성을 크게 떨어뜨린다.
- 예외적으로 main 메소드는 오직 JVM만이 호출하므로
Exception 을 던지도록 선언해도 괜찮다.
비검사 예외도 검사 예외처럼 문서화해두면 좋다.
- 자바 언어가 요구하는 것은 아니지만 비검사 예외도 문서화해두면 좋다.
- 비검사 예외는 일반적으로 프로그래밍 오류를 뜻한다.
- 비검사 예외를 문서화해두면 프로그래머는 자연스레 해당 오류가 발생하지 않도록 코딩하게 된다.
- 잘 정비된 비검사 예외 문서는 사실상 그 메소드를 성공적으로 수행하기 위한 전제조건이 된다.
- public 메소드라면 필요한 전제조건을 문서화해야 하며, 그 수단으로 가장 좋은 것이 비검사 예외들을 문서화하는 것이다.
발생 가능한 비검사 예외를 문서화하는 것은 인터페이스 메소드에서 특히 더 중요하다.
- 이 조건이 인터페이스의 일반 규약에 속하게 되어 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문이다.
메소드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메소드 선언의 throws 목록에 넣지 말자.
- 검사냐 비검사냐에 따라 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분해주는 게 좋다.
- 이를 구분하면 프로그래머는 어느 것이 비검사 예외인지를 바로 파악할 수 있게 된다.
비검사 예외를 모두 문서화하는 것은 현실적으로 불가능할 때도 있다.
- 예컨대 다른 사람이 작성한 클래스를 사용하는 메소드가 있다고 하면 모든 예외를 공들여 문서화했더라도 다른 사람이 작성한 클래스가 새로운 비검사 예외를 던지게 수정된다면, 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 될 것이다.
한 클래스에 정의된 많은 메소드가 같은 이유로 같은 예외를 던진다면 그 예외를 클래스의 문서화 주석에 추가할 수도 있다.
- 예를 들어 클래스의 문서화 주석에 "이 클래스의 모든 메소드는 인수로 null이 넘어오면 NullPointerException을 던진다" 고 적을 수 있다.
핵심 정리
- 메소드가 던질 가능성이 있는 모든 예외를 문서화하라.
- 검사 예외든 비검사 예외든, 추상 메소드든 구체 메소드든 모두 마찬가지다.
- 문서화에는 자바독의
@throws 태그를 사용하면 된다.
- 검사 예외만 메소드 선언의 throws 문에 일일이 선언하고, 비검사 예외는 메소드 선언에는 기입하지 말자.
- 발생 가능한 예외를 문서로 남기지 않으면 다른 사람이 그 클래스나 인터페이스를 효과적으로 사용하기 어려워질 수 있다.
참고 자료