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

메서드가 발생시키는 예외는 해당 메서드를 올바르게 사용하는 데 매우 중요한 정보이므로 각 메서드가 발생시키는 예외를 하나씩 문서화하는 것이 필요합니다.

 

Checked Exception은 항상 별도로 선언하고, 각 예외가 발생하는 상황을 JavaDoc의 @throws 태그로 문서화하라

• 공통 상위 예외 클래스 하나로 뭉뚱그려 선언하는 일은 지양해야 함
  • 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못할 뿐만 아니라 같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있어 API 사용성을 떨어뜨림 
  • ex) Exception이나 Throwable을 throw 한다고 선언해서는 안됨
  • 예외 케이스: main 메서드는 JVM만이 호출하므로 Exception으로 묶어서 던지도록 선언해도 괜찮음

 

1. 안 좋은 예

 

 

public void func() throws Exception {}

view raw .java hosted with ❤ by GitHub

 

 

2. 권장하는 예

	/**
	* 주어진 파라미터를 기준으로 데이터베이스를 조회하는 메서드입니다.
	*
	* @param param 데이터베이스 조회에 사용될 파라미터 (숫자형 데이터여야 함)
	* @throws IllegalStateException - 메서드가 호출되는 상태가 부적절할 때 발생하는 예외
	* @throws SQLException - 데이터베이스 조회 중 발생한 SQL 예외
	* @throws NumberFormatException - param이 숫자형 데이터가 아닌 경우 발생하는 예외
	*/
	public void func(String param) throws IllegalStateException, SQLException, NumberFormatException {
	// param을 기준으로 DB 조회
	}

view raw .java hosted with ❤ by GitHub

 

Unchecked Exception 또한 문서화하라

• 자바에서 요구하는 것은 아니지만 RuntimeException을 상속하는 Unchecked Exception도 Checked Exception처럼 문서화하는 것을 권장
• Unchecked Exception은 일반적으로 프로그래밍 오류를 뜻하는데 개발자가 발생시킬 수 있는 오류를 명시하면 개발자는 자연스럽게 문서화된 오류들이 발생하지 않도록 개발하게 됨
• 잘 정비된 Unchecked Exception 문서는 해당 메서드를 성공적으로 수행하기 위한 전제조건
  • public 메서드라면 필요한 전제 조건을 문서화해야 하며, 그 수단으로 가장 좋은 것이 Unchecked Exception을 문서화하는 것
  • 인터페이스의 일반 규약에 속하게 되어 인터페이스를 구현한 모든 구현체가 일관되게 동작할 수 있도록 인터페이스 메서드에서 발생 가능한 Unchecked Exception을 문서로 남기는 것을 권장

 

Unchecked Exceptoin은 메서드 시그니처에 추가하지 말라

• 메서드가 던질 수 있는 예외를 각각 @throws 태그로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 않는 것을 권장
• 예외가 Checked냐 Unchecked냐에 따라 개발자가 해야 할 일이 달라지므로 이 둘을 확실히 구분하는 것이 좋음
• JavaDoc은 메서드 시그니처의 throws 절에 등장하는 예외와 메서드 주석의 @throws 태그에 명시된 예외, 그리고 @throws 태그에만 명시된 예외를 시각적으로 구분하여 제공하기 때문에 단번에 Unchecked Exception인지 알 수 있음

 

한 클래스에서 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 클래스 설명에 추가하라

• NullPointerException이 가장 흔한 사례
• 클래스의 문서화 주석에 "이 클래스의 모든 메서드는 인수로 null이 넘어오면 NullPointerException을 던진다."라고 적는 것을 권장

 

	/**
	* 이 클래스는 NullPointerException이 흔히 발생할 수 있으며,
	* 모든 메서드는 인수로 null이 전달될 경우 NullPointerException을 발생시킬 수 있습니다.
	*/
	public class Example {
	/**
	* 예시 메서드입니다.
	*
	* @param input 입력 값 (null 허용 안 함)
	* @throws NullPointerException 입력이 null인 경우 발생하는 예외
	*/
	public void exampleMethod(Object input) throws NullPointerException {
	if (input == null) {
	throw new NullPointerException("Input cannot be null.");
	}
	// 메서드 동작
	}
	/**
	* 다른 예시 메서드입니다.
	*
	* @param data 데이터 (null 허용 안 함)
	* @throws NullPointerException 데이터가 null인 경우 발생하는 예외
	*/
	public void anotherExampleMethod(String data) throws NullPointerException {
	if (data == null) {
	throw new NullPointerException("Data cannot be null.");
	}
	// 메서드 동작
	}
	// 다른 메서드들...
	}

view raw .java hosted with ❤ by GitHub

 

참고

이펙티브 자바