더북(TheBook)

그러니 이 주석으로 충분하겠습니까? Queue 인스턴스 대신 널을 전달하면 어떤 일이 생길지 알겠나요? 특정 입력에 대해 런타임 예외가 발생할까요?

대답은 “아니오. 아니오. 그리고 모르겠습니다.”입니다. JavaDoc 주석이 있는데도 메서드가 어떻게 동작하는지 전혀 알 수 없습니다. 이 메서드를 사용하면 코드가 어떻게 동작할지 더 이상 확신할 수 없습니다. API를 개발 중이라면 문제가 더 큽니다.

어떻게 바꿀 수 있는지 봅시다.

interface CargoShip {
    Stack<Supply> unload();
    /**
     * 제품을 화물선에 싣는다.
     *
     * <p>
     * 남은 용량만큼만 제품을 싣게 해준다.
     *
     * 예:
     * <pre>
     * int capacity = cargoShip.getRemainingCapacity(); // 1
     * Queue&lt;Supply> supplies = Arrays.asList(new Supply("Apple"));
     * Queue&lt;Supply> spareSupplies = cargoShip.load(supplies);
     * spareSupplies.isEmpty(); // 참
     * cargoShip.getRemainingCapacity() == 0; // 참
     * </pre>
     *
     * @param 적재할 제품; 널이면 안 된다.
     * @return 용량이 작아 실을 수 없었던 제품;
     *          모두 실었다면 empty
     * @throws 제품이 널이면 NullPointerException
     * @see CargoShip#getRemainingCapacity() 용량을 확인하는 함수
     * @see CargoShip#unload() 제품을 내리는 함수
     */
    Queue<Supply> load(Queue<Supply> supplies);

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