/**
 * 이 클래스는 화물선을 나타낸다.
 * 제품의 {@link Stack}를 내릴 수 있고 제품의 {@link Queue}를 실을 수 있으며
 * long 타입으로 remainingCapacity를 보여줄 수 있다.
 */
interface CargoShip {
    Stack<Supply> unload();
    Queue<Supply> load(Queue<Supply> supplies); 
    int getRemainingCapacity(); 
}

이미 알고 있겠지만 모든 퍼블릭 클래스나 인터페이스는 JavaDoc으로 설명해야 합니다. 이것은 대부분의 자바 프로젝트에 적용되는 규칙입니다.

문제는 대부분의 개발자가 JavaDoc을 맨 나중에 마감이 임박했을 때 쓴다는 점입니다. 이렇게 되면 위 주석처럼 됩니다. 외견상으로는 괜찮아 보이죠.

JavaDoc 주석은 요약과 클래스 기능에 대한, 더 상세한 모든 설명을 포함합니다. 심지어 @link 표기를 사용해 클래스가 사용했던 자료 구조와도 연결해줍니다.

하지만 패키지를 JavaDoc으로 구조화하기에서처럼 구조화가 덜 되었습니다. 요약과 상세 설명이 수직적 분리 없이 서로 붙어 있습니다. 그래서 각각 떼어놓고 식별하기 어렵습니다. 게다가 주석에 오류까지 있습니다.