[Effective Java] 62. 메서드에서 던져지는 모든 예외에 대해 문서를 남겨라.

api 문서에는 예외에 대한 내용도 명시되어 있어야 한다. 문서에 남길때는 @throws 태그를 이용한다.

1. Checked Exception

Checked Exception의 경우 이를 사용하는 곳에서 반드시 try-catch로 잡아야 하기 때문에 문서에도 명시해 주어야 한다.

2. Unchecked Exception

모든 Unchecked Excetion을 명시할 필요는 없지만 주의해서 문서에 남겨주면 좋다.

Unchecked Excetion은 보통 메서드 동작을 위한 선행조건인 경우가 많다. 따라서 이를 문서에 명시하면 선행조건 명시를 효과적으로 할 수 있다.

2.1. 주의할점.

Javadoc @throws 를 통해 Unchecked Exception을 명시하는 것은 좋지만 실제 메서드 선언부 throws 뒤에 이러한 Exception을 나열하지는 마라.

그래야 API를 사용하는 사람이 어떤것이 Checked Exception이고 어떤것이 Unchecked Exception인지 구분할 수가 있다. (Javadoc도 이를 구분할 수 있게 보여줌)

2.2. 모든 예외를 문서에 남기기 어려운 경우.

 독립적으로 구현된 다른 클래스 A의 메서드를 B클래스가 호출한다.
 B 클래스 개발자는 문서에 Unchecked Exception이 발생할수 있는 경우까지 남겼다.
 그런데 이후에 A클래스의 메서드 구현이 일부 수정되어 발생가능한 UnChecked Exception이 늘어났다.
 이 경우 B클래스는 수정한적이 없지만 문서에 명시되지 않은 Exception이 발생할 수 있다.

위와 같이 다른 구현의 수정사항때문에 문서상에 모든 예외를 명시할 수 없는 경우가 있다. 이는 어쩔 수 없다.

위의 예 말고도 동일한 Exception을 던지는 메서드가 많다면 메서드마다 문서에 모두 명시하지 말고 Class의 주석에 아래와 같이 남겨도 된다.

이 클래스에 있는 모든 메서드는 인자로 null이 전달되면 NullPointerException을 발생시킨다.