[Effective Java] 메소드가 던지는 모든 예외를 문서화하자.

[Effective Java] 메소드가 던지는 모든 예외를 문서화하자.

-
Javadoc 의 @throws 태그를 사용해서 항상 checked 예외는 별도로 선언하고, 각 예외가 발생하는 상황을 정확하게 문서화하자.
메소드가 던지는 예외가 많다고 해서 메소드 명세에 각 예외를 정확하게 선언하지 않고, 그 예외 클래스의 대표적인 슈퍼 클래스만 함축해서 나타내면 안 된다.


-
unchecked 예외의 문서 내역은 메소드가 성공적으로 실행되기 위한 사전조건(precondition)을 효과적으로 나타낸다.


-
인터페이스에 정의된 메소드의 경우 자신이 던질 수 있는 unchecked 예외를 문서화하는 것이 "특히" 중요하다.
그 인터페이스의 보편적 계약 중 일부분이 되며, 인터페이스를 구현하는 여러 구현체들 간의 공통된 행동을 나타내기 때문이다.


-
Javadoc 의 @throws 태그를 사용해서 메소드가 던질 수 있는 unchecked 예외를 문서화 하자.
그러나 메소드 선언부의 throws 키워드에는 unchecked 예외를 넣지 말자.


-
만일 같은 클래스의 여러 메소드에서 동일한 이유로 어떤 한 가지 예외를 던진다면, 그 예외를 각 메소드에 개별적으로 문서화하는 것보다는 클래스의 문서화 주석에 그 예외의 설명을 추가하는 것이 좋다.

Summary

각 메소드에서 던질 수 있는 모든 예외를 문서화하자.
checked 예외는 물론 unchecked 예외도 마찬가지이며, 실제 메소드는 물론 추상 메소드도 마찬가지다.
메소드 선언부의 throws 키워드에는 checked 예외는 넣되, unchecked 예외는 넣지 말자.
만일 우리 메소드에서 던질 수 있는 예외를 문서화하는데 실패하면(혹은 안 하거나 잘못하면), 다른 사람들이 우리 클래스나 인터페이스를 사용하기 어려울 것이다.

@throws, checked exception, checked 예외, Effective JAVA, javadoc, precondition, TAG, throws, unchecked, unchecked exception, unchecked 예외, [Effective Java] 메소드가 던지는 모든 예외를 문서화하자., 개별적 문서화, 공통된 행동, 메소드, 메소드 선언부, 모든 예외, 문서화, 보편적 계약, 사전 조건, 예외, 인터페이스, 정의, 추상 메소드, 클래스 문서화 주석, 키워드, 태그