메서드가 던지는 모든 예외를 문서화 하라

메서드가 던지는 예외는 그 메서드를 올바로 사용하는데 아주 중요한 정보다.

검사 예외

검상 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 javadoc의 @throw 태그를 사용하여 정확히 문서화 하자. 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자. ex) Exception이나 Throwable을 던진다고 선언해서는 안된다.

비검사 예외

비검사 예외도 검사 예외처럼 정성껏 문서화 해두면 좋다.

비검사 예외는 일반적으로 프로그래밍 오류를 뜻하는데, 자신이 일으킬 수 있는 오류들을 알려주면 사용하는 입장에서 도움이 된다.

메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자 검사냐 비검사냐에 따라 사용자가 해야 할 일이 달라지므로 둘을 구분해주는것은 좋다.

현실적으로 불가능할때

비검사 예외는 문서화하기 불가능할 때도 있다. 예컨대 다른 사람이 작성한 클래스를 사용하는 메서드가 있을때, 발생가능한 모든 비검사 예외를 문서화 했다고 하더라도, 다른 사람이 작성한 클래스쪽에 수정사항이 있다면 문서화 되지 않은 새로운 비검사 예외를 전파하게 될것이다.

정리

메서드가 던질 가능성이 있는 모든 예외를 문서화 해라