[Effective Java] 아이템 74. 메서드가 던지는 모든 예외를 문서화하라

EFFECTIVE JAVA(이펙티브 자바)

 

이 포스팅에서 작성하는 내용은 EFFECTIVE JAVA(이펙티브자바) 에서 발췌하였습니다.

---

아이템 74. 메서드가 던지는 모든 예외를 문서화하라

 

검사 예외 문서화

• 메서드가 던지는 예외는 그 메서드를 올바로 사용하는데 필요한 정보다.
• 검사 예외는 항상 따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자.
• 공통 상위 클래스 하나로 뭉뜽그려 선언하는 것은 좋지 않다.
  • 메서드 사용자에게 각 예외에 대처 방안을 줄 수 없다.
  • 같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있어 API 사용성을 크게 떨어뜨린다.
  • 이 규칙에 유일한 예외는 main 메서드다. (main은 오직 JVM만 호출하기 때문)

 

 

비검사 예외 문서화

• 자바 언어가 요구하는 것은 아니지만 비검사 예외도 검사 예외처럼 정성껏 문서화 해두면 좋다.
• 비검사 예외는 일반적으로 프로그래밍 오류를 뜻하며, 자신이 일으킬 수 있는 오류들이 무엇인 지 알려주면 프로그래머는 해당 오류를 피할 수 있다.
• public 메서드라면 필요한 전제조건을 문서화해야 하며, 그 수단으로 가장 좋은 것이 비검사 예외들을 문서화 하는 것이다.
• 이는 인터페이스 메서드에서 특히 중요하다. 이 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문
• 메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자.
• 한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 그 예외를 클래스 설명에 추가하는 방법도 있다.

 

 

정리

• 메서드가 던질 가능성이 있는 모든 예외를 문서화하자.
• 검사 예외든 비검사 예외든, 추상 메서드든 구체 메서드든 마찬가지이다.
• 문서화에는 자바독 @throws 태그를 사용하면 된다.
• 검사 예외만 메서드 선언의 throws 문에 일일이 선언하고, 비검사 예외는 메서드 선언에는 기입하지 말자.
• 발생 가능한 예외를 문서로 남기지 않으면 다른 사람이 그 클래스나 인터페이스를 효과적으로 사용하기 어려울 수 있다.