더북(TheBook)

위 예제의 JavaDoc은 형편없습니다. 요약문은 새로운 정보를 전달하지 않을 뿐만 아니라 전혀 쓸모가 없습니다. 두 번째 생성자의 두 번째 요약문도 핵심에서 벗어나 있습니다. supplies를 정확히 어떻게 추가하나요? initialSupplies 매개변수를 참조해 추가하나요? 아니면 다른 메서드를 쓰나요?

또한 두 생성자의 관계도 전혀 추론할 수 없습니다. 일반적으로 외부 클래스를 사용할 때는 소스 코드를 읽지 않습니다. JavaDoc만 보죠. 따라서 생성자*의 JavaDoc 주석은 프로그래머가 생성자를 사용하는 데 필요한 모든 요소를 설명해야 합니다.

그렇다면 어떤 정보를 알아야 이 클래스를 올바르게 사용할 수 있을까요?

class Inventory {

    List<Supply> supplies;

    /**
     * 빈 재고를 생성한다.
     *
     * @see Inventory#Inventory(Collection) 초기 제품을 초기화하는 함수
     */
    Inventory() {
        this(new ArrayList<>());
    }

    /**
     * 제품을 처음으로 선적한 재고를 생성한다.
     *
     * @param initialSupplies  제품을 초기화한다.
     *                         널이면 안 되고 빌 수 있다.
     * @throws NullPointerException initialSupplies가 널일 때
     * @see Inventory#Inventory() 제품없이 초기화하는 함수
     */
    Inventory(Collection<Supply> initialSupplies) {
        this.supplies = new ArrayList<>(initialSupplies);
    }
}

 

 


* 때로는 생성자를 일제히 숨기고 의미 있게 명명한 정적 메서드, 즉 내부적으로 흔히 팩터리 메서드로 불리는 숨겨진 생성자를 호출하는 메서드만 노출하는 것이 더 편리합니다.

신간 소식 구독하기
뉴스레터에 가입하시고 이메일로 신간 소식을 받아 보세요.