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

각 메서드가 던지는 예외 하나하나를 문서화하는 데 충분한 시간을 쏟아야 한다.

검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자.

 

 

 

공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가자

극단적인 예로 메서드가 Exception이나 Throwable을 던진다고 선언해서는 안 된다.

 

/**
 *
 * @return secondField
 * @throws Throwable
 * @throws Exception
 */
public int getSecondField() throws IllegalAccessError {
    return secondField;
}

 

 

 

 

비검사 예외도 문서화두면 좋다

비검사 예외는 일반적으로 프로그래밍 오류를 뜻하는데 자신이 일으킬 수 있는 오류들이 무엇인지 알려주면 프로그래머는 자연스럽게 해당 오류가 나지 않도록 코딩하게 된다. 발생 가능한 비검사 예외를 문서로 남기는 일은 인터페이스 메서드에서 특히 중요하다. 이 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문이다.

 

 

 

 

비검사 예외는 메서드 선언의 throws 목록에 넣지 말자

자바독 유틸리티는 메서드 선언의 throws 절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시작적으로 구분해준다.

 

/**
 *
 * @return secondField
 * @throws NullPointerException if parameter is null or empty 비검사예외
 * @throws IllegalAccessError if someone access 검사예외
 */
public int getSecondField() throws IllegalAccessError {
    return secondField;
}

 

 

 

 

비검사 예외 문서화가 불가능한 경우도 있다

다른 사람이 작성한 클래스를 사용하는 메서드가 있다고 해보자. 그리고 발생 가능한 모든 예외를 공들여 문서화했다. 하지만 후에 이 외부 클래스가 새로운 비검사 예외를 던지게 수정된다면, 아무 수정도 하지 않은 우리 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 될 것이다.

public class Util {
  /**
	 * @throws NullPointerException
   * @throws IndexOutofBoundsException
	 */
	public static void capture() {
		...
	}
}

public class Client {

  /**
	 * @throws NullPointerException
	 */
	public void execute() {
		...
		Util.capture();
	}

  /**
	 * @throws NullPointerException
   * @throws IndexOutofBoundsException
	 */
	public void test() {
		...
		Util.capture();
	}
}

 

 

 

 

 

예외 문서화를 클래스 단위로 올리자

 

한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 그 예외를 (각각의 메서드가 아닌) 클래스 설명에 추가하는 방법도 있다.

/**
 *
 * @throws IllegalAccessError
 */
public class Test {

	public void add() throws IllegalAccessError  {
		...
	}

	public void minus() throws IllegalAccessError {
		...
	}