한 줄 요약: 제목이 곧 내용이다. Exception을 어떻게 문서화하는 것이 좋은지 소개해주는 아이템이었다.
Checked Exception과 Unchecked Exception
상위 타입으로 뭉뚱그려 throws 키워드 선언하지 말기
public void checkedException()
throws Exception {
Date date = DateFormat.getDateInstance().parse("2017-01-01");
System.out.println(date);
Thread.sleep(1000);
}
Java
복사
물론 컴파일 오류는 나지 않는다.
극단적인 예시이기는 하지만 이 메소드를 사용하는 클라이언트 측에서는 이 예외에 대해서 어떻게 예측해야 하는지 전혀 힌트를 얻을 수 없다…
public void checkedException()
throws ParseException, InterruptedException {
Date date = DateFormat.getDateInstance().parse("2017-01-01");
System.out.println(date);
Thread.sleep(1000);
}
Java
복사
ParseException, InterruptedException가 각각 발생할 수 있음을 명확하게 명시해주어야 한다.
만약 ParseException, InterruptedException가 공통된 상위 타입의 클래스가 있어, 공통으로 명시해주고 싶은 유혹이 들더라도, 반드시 따로 따로 적어주어야 한다.
public static void main(String[] args) {
ExceptionTest exceptionTest = new ExceptionTest();
try {
exceptionTest.checkedException();
} catch (ParseException e1) {
e1.printStackTrace();
System.out.println("날짜 정보를 파싱할 수 없습니다.");
} catch (InterruptedException e2) {
e2.printStackTrace();
System.out.println("스레드 sleep 중에 인터럽트가 발생했습니다.");
}
}
Java
복사
이렇게 해야, 클라이언트 측에서도 상황에 맞는 적절한 예외 처리를 수행할 수 있을 것이다.
@throws 자바독의 태그를 이용하여 정확히 명세하기
/**
* checked exception 예제
*
* @throws ParseException 날짜 정보를 파싱할 수 없을 때, 발생합니다.
* @throws InterruptedException 스레드 sleep 중에 인터럽트가 발생했을 때, 발생합니다.
*/
public void checkedException()
throws ParseException, InterruptedException {
Date date = DateFormat.getDateInstance().parse("2017-01-01");
System.out.println(date);
Thread.sleep(1000);
}
Java
복사
이렇게 @throws 자바독의 태그를 이용하여 명세를 하면 클라이언트 측에서 이 메소드를 사용할 때, 어떤 상황에서 어떤 에러가 발생하는지를 명확히 인지하고 코드를 작성할 수 있다.
Unchecked Exception도 문서화하기
자바 언어에서 필수적으로 요구하는 것은 아니지만, Unchecked Exception도 명세를 한다면 프로그래머가 자연스럽게 해당 오류가 발생하지 않도록 코딩하는 효과를 줄 수 있기 때문에 도움이 된다.
단, Unchecked Exception는 throws 목록에 넣지는 말아야 한다.
한 클래스에 여러 메소드가 동일한 이유로 예외를 던진다면, 클래스에 주석을 달기
NullPointerException 같이 한 클래스에서 여러 메소드가 동일한 이유로 예외를 던지는 경우들이 종종 있다.
이런 경우에는 메소드 각각마다 주석을 남기기보다 클래스 위에 주석을 남길 수도 있다.
저자의 핵심 정리
메소드가 던질 가능성이 있는 모든 예외를 문서화하라.
Checked Exception이든 Unchecked Exception이든, 추상 메소드이든, 구체 메소드이든 마찬가지다.
문서화에는 자바독의 @throws 태그를 사용하면 된다.
Checked Exception만 메소드 뒤에 throws 문을 각각 선언하고, Unchecked Exception는 기입하지 말자.
발생 가능한 예외를 문서로 남기지 않는다면, 다른 사람이 그 클래스나 인터페이스를 효과적으로 사용하기 어렵거나 불가능할 수 있다.