그러니 이 주석으로 충분하겠습니까? Queue 인스턴스 대신 널을 전달하면 어떤 일이 생길지 알겠나요? 특정 입력에 대해 런타임 예외가 발생할까요?
대답은 “아니오. 아니오. 그리고 모르겠습니다.”입니다. JavaDoc 주석이 있는데도 메서드가 어떻게 동작하는지 전혀 알 수 없습니다. 이 메서드를 사용하면 코드가 어떻게 동작할지 더 이상 확신할 수 없습니다. API를 개발 중이라면 문제가 더 큽니다.
어떻게 바꿀 수 있는지 봅시다.
interface CargoShip { Stack<Supply> unload(); /** * 제품을 화물선에 싣는다. * * <p> * 남은 용량만큼만 제품을 싣게 해준다. * * 예: * <pre> * int capacity = cargoShip.getRemainingCapacity(); // 1 * Queue<Supply> supplies = Arrays.asList(new Supply("Apple")); * Queue<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(); }