요약문은 단순히 인터페이스명을 반복할 뿐 별다른 역할을 못 합니다. 설상가상 CargoShip은 주석에 명시된 것처럼 클래스가 아닌 인터페이스이니 틀리기까지 했습니다.
상세 설명은 인터페이스의 메서드 서명을 되풀이합니다. 얼마 안 지나 실제 코드와 부합하지 않을 수도 있죠. getRemainingCapacity()가 롱(long) 값을 더 이상 반환하지 않으면요.
그렇다면 단순히 인터페이스의 메서드 서명만 반복하지 않는 유용한 주석은 어떻게 작성할까요?
/** * 화물선은 용량에 따라 제품을 싣고 내릴 수 있다. * * <p> * 제품은 순차적으로 선적되고 LIFO(last-in-first-out) 순으로 내려진다. * 화물선은 용량만큼만 제품을 저장할 수 있다. * 용량은 절대 음수가 아니다. */ interface CargoShip { Stack<Supply> unload(); Queue<Supply> load(Queue<Supply> supplies); int getRemainingCapacity(); }