이펙티브 자바 - Item73. 메서드가 던지는 모든 예외를 문서화하라

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

---

• 메서드가 던지는 예외는 그 메서드를 올바로 사용하는데 아주 중요한 정보입니다. 따라서 각 메서드가 던지는 예외는 하나하나 문서화하는데 충분한 시간을 투자해야 합니다.
• 검사 예외(Checked Exception)은 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 어노테이션을 사용해 정확히 문서화해야 합니다.

 

💡 공통 상위 클래스 하나로 뭉뚱그려 선언하는 일은 삼가야 합니다.

• 극단적인 예로 Exception이나 RuntimeException, Throwable을 던진다고 선언해서는 안됩니다. 메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못할뿐더러, 같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있습니다.

 

💡 비검사 예외도 문서화해두면 좋습니다.

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

 

💡 비검사 예외는 메서드 선언의 throws 목록에 넣지 말아야 합니다.

• 아래 메서드는 문제가 있습니다. 예외가 검사냐 비검사냐에 따라 메서드 호출자가 해야 할 일이 달라지기 때문에 이 둘을 구분해주는 것이 좋습니다.

 

• 아래처럼 검사예외와 비검사 예외를 선언부 throws 절과 주석의 @throws 태그로만 구분해도 자바독 문서에서 시각적으로 구분해준다고 합니다. 그래서 개발자는 예외가 검사예외인지 비검사 예외인지 알 수 있게 됩니다.

 

💡 비검사 예외 문서화가 불가능한 경우

• 항상 비검사 예외의 문서화가 가능한 것만은 아닙니다. 클래스 수정으로 인해 새로운 비검사 예외를 던지게 되어도 소스 호환성, 바이너리 호환성이 그대로 유지된다는 게 큰 이유입니다. 예를들어 다른 사람이 작성한 클래스를 사용한 메서드가 있다고 가정했을 경우 외부 클래스가 나중에 새로운 비검사 예외를 던지게 수정된다면 아무 수정도 하지 않은 우리 메서드에서는 문서에 정의되지 않은 새로운 비검사 예외를 전파하게 될 것입니다.

 

💡 중복된 예외 합치기

• 아래는 각 메서드마다 NPE가 발생하므로 이에 대한 설명이 중복될 수 있습니다. 이러한 경우 메서드 주석을 메서드 레벨이 아닌 클레스 레벨로 올려 문서화할 수 있습니다.

 

• 아래 코드는 문서화를 클래스 레벨로 올린 예제입니다.

 

✔️ 정리

• 메서드에서 예외를 던질 가능성이 있는 경우 문서화를 해야합니다.
• 검사 예외는 메서드의 선언부의 throws 절에 선언하고, 비검사 예외는 @throws 어노테이션에 작성을 하여 구분을 하는 것이 좋습니다.