스미스요원

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

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

• 검사 예외가 발생하는 상황을 자바독의 @throws 태그를 사용해 정확히 문서화하자.

• 공통 상위 클래스 하나로 뭉뚱그려 선언하지 말 것

    ◦  예) 메서드가 단순히 Exception 이나 Throwable을 던진다고 선언하면 안 된다.

          -  메서드 사용자가 세부적인 예외에 대처할 수 있는 힌트를 주지 못한다.

          -  같은 맥락에서 발생할 여지가 있는 다른 예외들까지 삼켜버릴 수 있다.

• 이렇게 해도 되는 유일한 메서드 : main 메서드

    ◦  main 메서드 를 호출하는 주체는 JVM 뿐이므로 Exception 을 던진다고 선언해도 괜찮다.

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

• 비검사 예외는 일반적으로 프로그래밍 오류를 뜻한다.

    ◦  즉 일으킬 수 있는 오류가 무엇인지 알면 프로그래머스는 해당 부분을 주의하여 코드를 작성할 수 있다.

    ◦  잘 정비된 비검사 예외 문서는 그 메서드를 성공적으로 수행하기 위한 전제 조건이 된다.

• public 메서드라면 필요한 전제 조건을 문서화해야 하는데(아이템 56), 그 수단으로 가장 좋은 것이 비검사 예외들을 문서화하는 것이다!

• 비검사 예외를 문서로 남기는 일은 인터페이스 메서드에서 특히 중요하다.

    ◦  이 조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문

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

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

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

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

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

    ◦  @throws 태그에만 명시한 예외

4. 비검사 예외의 문서화가 어려운 상황

• 비검사 예외도 문서화하라고 했지만, 현실적으로 불가능할 때도 있다.

    ◦  예시 상황

          -  다른 사람이 작성한 클래스를 사용하는 메서드가 있다고 하자.

          -  발생 가능한 모든 예외를 문서화 했다!

          -  후에 이 외부 클래스가 새로운 비검사 예외를 던지게 되었다!

          -  아무 수정도 되지 않은 메서드는 문서에 언급되지 않은 새로운 비검사 예외를 전파하게 된다!

5. 공통 예외는 메서드 단이 아닌, 클래스 단에 적자

• 한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던지는 경우, 그 예외를 각 메서드가 아닌 클래스 설명에 적어주는 방법도 있다.

    ◦  NullPointerException 이 가장 흔한 사례

    ◦  클래스의 문서화 주석에 ‘이 클래스의 모든 메서드는 인수로 null 이 넘어오면 NullPointerException 을 던진다’ 라는 식으로

         설명을 적어주면 된다.

6. 정리

• 메서드가 던질 수 있는 모든 예외를 문서화하라. (검사 예외 / 비검사 예외 / 추상 메서드 / 구체 메서드)

• 자바독 @throws 태그를 사용하라.

• 검사 예외는 메서드 선언의 throws 목록에 달고, 비검사 예외는 메서드 선언 쪽에는 달지 말자.

• 발생 가능한 예외를 문서로 남기지 않으면 클래스,인터페이스를 효과적으로 사용하기 어려울 수 있다.