210311_B책_클래스와 인터페이스를 JavaDoc으로 구조화하기

어제에 이어서 오늘도 javadoc에 관한 내용을 다루는데 오늘은 클래스와 인터페이스를 구조화한다.
대부분의 개발자가 JavaDoc을 맨 나중에 마감이 임박했을 때 쓰는데,
=>(나는 개발자가 아님에도 이해가 간다..)
그렇게 되면 아래 주석처럼 된다.

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

=>(javadoc 초보자인 내가 봤을 땐 군더더기 없어보이는데 지은이의 마음에는 안든다.)
외견상으로는 괜찮아보이는데,
일반 주석이 아닌 JavaDoc 주석은 요약과 클래스 기능에 대한, 더 상세한 모든 설명을 포함해야 한다.
우선 위 javadoc이 잘못된 점은

1. 요약과 상세설명이 붙어있다는 점.
2. 인터페이스인데 클래스라고 명시한 점.
3. Stack과 Queue에 대한 설명이 부족.

이러한 문제점을 바로 잡게된다면,

/**
 * 화물선은 용량에 따라 제품을 싣고 내릴 수 있다.
 *
 * <p>
 * 제품은 순차적으로 선적되고 LIFO(Last-In-First-Out) 순으로 내려진다.
 * 화물선은 용량만큼만 제품을 저장할 수 있다.
 * 용량은 절대 음수가 아니다.
 */
 
 interface CargoShip {
  Stack<Supply> unload();
  Queue<Supply> load(Queue<Supply> supplies);
  int getRemainingCapacity();
 }

주석의 최상단에 있는 요약문이 눈에 잘띄게 되고,
후입선출법 사용과 같은 동작을 더 상세히 설명하고 있다.

더불어 인터페이스를 호출할 때 capacity에 대해 보장하는 2가지 조건도 명시하고 있다.
java.util.List 인터페이스나 다른 인터페이스, 그리고 상태를 갖는 클래스의 JavaDoc 주석에서도
이러한 조건을 볼 수 있는데.
용량만큼만 저장과 음수가 아닌 것.
항상 참이므로 이러한 조건을 조건 불변이라고 부른다.

어제는 패키지였고 오늘은 인터페이스와 클래스였는데 매번 이렇게 작성하는 것이 중요하지만
개발자의 입장에서는 뭔가 귀찮을 것 같기도하고.. 물론 귀찮으면 안되지만 ^^

오늘의 코멘트: 역시 이후에 진행할 프로젝트에 적용을 해볼것!