1. 예외의 문서화

• 어떤 메서드가 발생시킬 수 있는 예외들은 javadoc 주석인 /** **/ 내부에서 @throws 어노테이션을 사용하여 명시할 수 있다.
• 예를 들면 다음과 같은 방식으로 진행이 가능하다.

/**
두 인자를 받아 더하기 연산을 진행해 그 결과를 반환하는 메서드

@param a 더하기 연산을 진행할 인자 a
@param b 더하기 연산을 진행할 인자 b
@return 두 인자 a, b를 더한 결과
@throws ArithmeticException 두 인자 중 하나라도 음수일 시 발생한다.
**/
public void plus(int a, int b) {
		if(a < 0 || b < 0) {
				throw new ArithmeticException();
		}

		return a + b;
}

• 메서드가 던지는 예외는 그 메서드를 올바로 사용하는데 아주 중요한 정보이다.
• 따라서 각 메서드가 던지는 예외 하나하나를 문서화하는데 충분한 시간을 쏟아야 한다.
• 검사 예외는 항상 따로따로 선언하고 각 예외가 발생하는 상황을 javadoc의 @throws 태그를 사용하여 정확히 문서화하자.
  • 가급적 하나의 예외를 사용해 모든 예외들을 퉁치는 행위는 삼가야 한다.
  • 이는 사용자가 해당 예외에 어떻게 대처해야 할 지 알려주는 힌트를 제공해주지 못할 뿐 더러 같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있어 API 사용성을 크게 저하시킨다.
• Java 언어가 요구하는 것은 아니지만 비검사 예외(RuntimeException을 상속받은 예외)도 검사 예외(Exception을 상속받은 예외)처럼 정성껏 문서화해두면 좋다.
  • 이는 비검사 예외는 일반적으로 프로그래밍 오류를 의미하는데 자신이 일으킬 수 있는 오류들이 무엇인지 알려준다면 개발자들은 자연스럽게 해당 오류가 발생하지 않도록 코딩하게 된다.
• 잘 정비된 비검사 예외 문서는 사실상 그 메서드를 성공적으로 수행하기 위한 전제조건이 된다.
• public 메서드라면 필요한 전제조건을 문서화해야 하며 그 수단으로 가장 좋은 것이 바로 비검사 예외들을 문서화하는 것이다.

2. 비검사 예외를 메서드 선언부의 throws 목록에 넣지 말자

• 검사인지 비검사인지에 따라 API 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분해주는 것이 좋다.
• Javadoc 유틸리티는 메서드 선언의 throws 절에 등장하고, 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해준다.

/**
@throws SomethingException ...
**/
public void doSomething() throws SomethingException {

}

/**
@throws SomethingRuntimeException
**/
public void doSomething2() {

}

• 즉 위의 두 메서드에서 각각의 예외들을 시각적으로 구분해줄 수 있다는 것이다.
• 비검사 예외도 모두 문서화하라고 하지만 현실적으로 불가능할 때도 있다.
• 클래스를 수정하면서 새로운 비검사 예외를 던지게 되어도 소스 호환성과 바이너리 호환성이 그대로 유지된다는 게 가장 큰 이유다.
  • 만약 다른 사람이 작성한 클래스를 사용하는 메서드가 있다고 하고, 발생 가능한 모든 예외를 공들여 문서화했다.
  • 하지만 이후 외부 클래스가 새로운 비검사 예외를 던지게 수정된다면 아무 수정도 하지 않은 우리 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 던지게 될 것이다.

클래스 설명에 예외 추가하기