Skip to content

Latest commit

 

History

History
163 lines (101 loc) · 4.35 KB

74_메서드가_던지는_모든_예외를_문서화하라_김재준.md

File metadata and controls

163 lines (101 loc) · 4.35 KB
Raw

ITEM 74

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

메서드가 던지는 예외는 그메서드를 올바로 사용하는데 아주 중요한 정보이다.

따라서

검사예외는 항상 따로따로 선언하고 각 예외가 발생하는 상황을 자바독의 @throws 태그를 사용하여 정확히 문서화하자

잘못된 예

public void examMethod() throws Exception {
    //TODO 무언가 하겟죠?
}

모든 예외를 Exception 으로 던지게 된다면 메서드 사용자는 각 예외에 대처할 수 있는 방법이 없다.

(다른 예외까지 삼켜버릴 수 있기 때문에 API 활용성이 크게 떨어진다.)

단 ! Main 메서드는 예외이다.(main 메서드는 오직 JVM 만이 호출 함으로)

올바른 예

/**
 * @throws SQLException SQL 이 잘못된 경우
 * @throws ClassNotFoundException 지정한 경로에 클래스파일이 존재하지 않는경우.
 */
public void examMethod() throws SQLException,ClassNotFoundException{
    Class.forName("/test/path/test.class");
    // TODO 무언가 했음.
}

자바 언어가 요구하는 것은 아니지만 비검사 예외도 검사 에외처럼 정성껏 문서화해두면 좋다.

단 메서드가 던질수 있는 예외를 각각 @throws 태그로 문서화하되 , 비검사 예외는 메서드 선언의 thorws 목록에 넣지말자.

**잘못된 예(비검사 예외를 thorws 목록에 포함시킴) **

/**
 * @throws SQLException SQL 이 잘못된 경우
 * @throws ClassNotFoundException 지정한 경로에 클래스파일이 존재하지 않는경우.
 * @throws NullPointerException 지정한 요소에 null 이 들어오는 경우
 */
public void examMethod() throws SQLException,ClassNotFoundException,NullPointerException{
    Class.forName("asd");
    // TODO 무언가 했음.
}

올바른 예

/**
 * @throws SQLException SQL 이 잘못된 경우
 * @throws ClassNotFoundException 지정한 경로에 클래스파일이 존재하지 않는경우.
 * @throws NullPointerException 지정한 요소에 null 이 들어오는 경우
 */
public void examMethod() throws SQLException,ClassNotFoundException{
    Class.forName("asd");
    // TODO 무언가 했음.
}

검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분하자.

한 클래스에 정의된 많은 메서드가 같은 이유로 같은 예외를 던진다면 그 예외를 각각의 메서드가 아닌 클래스 설명에 추가하는 방법이 있다.

예

public class Exam {
    /**
     * @throws SQLException SQL 이 잘못된 경우
     * @throws ClassNotFoundException 지정한 경로에 클래스파일이 존재하지 않는경우.
     * @throws NullPointerException 지정한 요소에 null 이 들어오는 경우
     */
    public void examMethod() throws SQLException,ClassNotFoundException{
        Class.forName("asd");
        // TODO 무언가 했음.
    }
    /**
     * @throws NullPointerException 지정한 요소에 null 이 들어오는 경우
     */
    public void examMethod2() throws IOException{
       //TODO 일하는 중 
    }
}

다음과 같이 여러 메서드에서 같은이유로 NullPointerException 을 던지는 경우 다음과 같이 클래스 설명에 추가하자 !

클래스 설명에 추가

/**
 * <p> {@code NullPointerException} 지정한 요소에 null 이 들어오는 경우 발생합니다.</p> 
 */
public class Exam {

    /**
     * @throws SQLException SQL 이 잘못된 경우
     * @throws ClassNotFoundException 지정한 경로에 클래스파일이 존재하지 않는경우.
     */
    public void examMethod() throws SQLException,ClassNotFoundException{
        Class.forName("asd");
        // TODO 무언가 했음.
    }

    public void examMethod2() throws IOException{
       //TODO 일하는 중
    }

}

결론

  1. 메서드가 던질 가능성이 있는 모든 예외를 문서화 하라
  2. 문서화에는 자바독 @throws 태그를 사용하면된다.
  3. 검사 예외만 메서드 선언의 throws 문에 일일이 선언하고 , 비검사 예외는 메서드 선언에는 기입하지말자.
  4. 발생가능한 예외를 문서로 남기지 않으면 다른 사람이 그 클래스나 인터페이스를 효과적으로 사용하기 어렵다.