210312_B책_메서드를 JavaDoc으로 구조화하기

어제는 인터페이스와 클래스를 Javadoc으로 구조화했고, 오늘은 더 깊은 메서드를 메서드를 진행한다.
메서드는 객체의 동작을 표현하고, 메서드를 호출하면 상태 변경과 부수 효과가 발생하게 된다.
그래서 어느 다른 형태의 JavaDoc보다 메서드의 JavaDoc 설명이 중요하다고 한다.

부족한 예를 한번 보자면,

interface CargoShip {
 Stack<Supply> unload();
 /**
  * {@link Supply} 를 싣는다.
  *
  * @param {@link Queue} 타입의 제품 제공
  * @return {@link Queue} 타입의 적재되지 않은 제품
  */
  
 Queue<Supply> load(Queue<Supply> supplies);
 
 int getRemainingCapacity();
}

예제에서 사용한 요약문과 @link 표기가 어떤가?
=>(이제 슬슬 뭔가 부족한데..? 라는게 느껴진다.)
또한 @param 과 @return 도 새로운 내용없이 메서드 명만 반복할 뿐이다.
그러니 이 주석으로 충분할까?
Queue 인스턴스 대신 널을 전달하면 어떤일이 생길까?
특정 입력에 대해 런타임 예외가 발생할까?
대답은 '아니요~ 모르겠어요~'

어떻게 바꿀수 있는지 보자.

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();
 }

=>(와 이정도 정성이면 진짜.. 못알아보는게 이상하지만 난 중간중간 모르겠는 것들이 있긴하다.)
훨씬 나아졌다.
마치 계약서를 읽듯이 JavaDoc 주석이 읽힌다.
입력과 내부 상태가 특정 출력과 상태 변경을 어떻게 보장하는지 명시하고있다.
위 주석은 설명과 코드 예제로 만든 훌륭한 사례이고,

<pre>는 XML환경이므로 <pre>내 < 문자를 반드시 &lt; 로 탈출시켜야 한다.

또한 null처럼 유효하지 않은 입력까지 @param 설명에 명시하면서 위반 시
NullPointerException을 @throws 한다고도 언급했다.
또한 @see 표기로 다른 메서드도 참조하고 있다.
메서드가 일으킨 효과를 되돌리는 방법이나 메서드 호출로 야기된 상태 변화를 관찰할 수 있는 방법을 설명한다.
=>(@see [관련 항목으로 외부 링크 또는 텍스트를 표시하거나, 다른 필드나 메소드에 대한 모든 참조 링크를 나타내는 경우에 사용한다.]
이렇게 설명해주니깐 진짜 알아듣기 쉽네..?)

오늘의 코멘트: 메서드에 대한 JavaDoc의 자세한 설명이 중요하다. 근데 그러면 api를 설명시에 분량이 엄청나지겠네..?