<aside> 📚 메서드가 던지는 예외는 그 메서드를 올바로 사용하는데 아주 중요한 정보이므로, 꼭 문서화 해주자

</aside>

1. 검사 예외를 문서화하라

• 검사 예외가 발생하는 상황을 자바독의 @throws 태그를 사용해 정확히 문서화하자.
• 공통 상위 클래스 하나로 뭉뚱그려 선언하지 말 것
  • 예) 메서드가 단순히 Exception 이나 Throwable을 던진다고 선언하면 안 된다.
    • 메서드 사용자가 세부적인 예외에 대처할 수 있는 힌트를 주지 못한다.
    • 같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있다.
• 이렇게 해도 되는 유일한 메서드 : main 메서드
  • main 메서드 를 호출하는 주체는 JVM 뿐이므로 Exception 을 던진다고 선언해도 괜찮다.

2. 비검사 예외를 문서화하라

• 비검사 예외는 일반적으로 프로그래밍 오류를 뜻한다.
  • 즉 일으킬 수 있는 오류가 무엇인지 알면 프로그래머스는 해당 부분을 주의하여 코드를 작성할 수 있다.
  • 잘 정비된 비검사 예외 문서는 그 메서드를 성공적으로 수행하기 위한 전제 조건이 된다.
• public 메서드라면 필요한 전제 조건을 문서화해야 하는데(아이템 56), 그 수단으로 가장 좋은 것이 비검사 예외들을 문서화하는 것이다!
• 비검사 예외를 문서로 남기는 일은 인터페이스 메서드에서 특히 중요하다.
  • 이 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문

3. 검사 예외와 비검사 예외를 구분하라

• 예외를 @throws 로 문서화하되, 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자.

• 검사 예외인지, 비검사 예외인지에 따라 해야할 일이 달라지므로 둘을 확실히 구분해주는 것이 좋다.

• 자바독 유틸리티는 아래 두 상황을 시각적으로 구분해주니까 잘 활용하자.

  • 메서드 선언의 throws 절에 등장하고, 메서드 주석의 @throws 태그에도 명시한 예외
  • @throws 태그에만 명시한 예외

  

  

4. 비검사 예외가 어려운 상황

• 비검사 예외도 문서화하라고 했지만, 현실적으로 불가능할 때도 있다.
  • 예시 상황
    • 다른 사람이 작성한 클래스를 사용하는 메서드가 있다고 하자.
    • 발생 가능한 모든 예외를 문서화 했다!
    • 후에 이 외부 클래스가 새로운 비검사 예외를 던지게 되었다!
    • 아무 수정도 되지 않은 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 된다!