와 근데 JavaDoc으로 못하는 주석은 없구나.. 하긴..
오늘은 생성자를 JavaDoc으로 구조화해본다.
자바에는 의미 있고 알맞은 이름을 할당할 수 없는 특수한 메서드 유형이 하나 있는데!
바로 생성자이다.
왜냐하면 생성자명은 무조건 클래스명과 같아야 하기때문이다.
다른 메서드보다 목적이 더 확실하지만 잘 사용하지 못하면 객체에 문제가 생긴다.
그래서 JavaDoc 주석은 생성자에 대해 의미 정보를 적절히 설명해야 한다.
class Invertory {
List<Supply> supplies;
/**
* 새 Inventory의 생성자
*/
Inventory() {
this(new ArrayList<>());
}
/**
* 새 Inventory의 또 다른 생성자
* 제품을 Inventory에 추가할 수 있는 생성자
*/
Inventory((Collection<Supply> initialSupplies) {
this.supplies = new ArrayList<>(initialSupplies);
}
}요약문은 새로운 정보를 전달하지 않을 뿐만 아니라 전혀 쓸모없다.
또한 두 번째 생성자의 요약문도 핵심에서 벗어나있다.
supplies 를 정확히 어떻게 추가하나?
initialSupplies 매개변수를 참조해 추가하나?
이러한 조건이 명시되어 있질 않고,
일반적으로 외부 클래스를 사용할 때는 소스 코드를 읽지 않는다고 한다. JavaDoc만 본다고..
=>(이러면 JavaDoc이 매우매우 중요해졌다.)
따라서 생성자의 JavaDoc 주석은 프로그래머가 생성자를 사용하는 데 필요한 모든 요소를 설명해야 한다.
class Invertory {
List<Supply> supplies;
/**
* 빈 재고를 생성한다.
* @see Inventory#Inventory((Collection) 초기 제품을 초기화하는 함수
*/
Inventory() {
this(new ArrayList<>());
}
/**
* 제품을 처음으로 선적한 재고를 생성한다.
*
* @param initialSupplies 제품을 초과한다.
* 널이면 안되고 빌 수 있다.
* @throws NullPointerException initialSupplies가 널일 때
* @see Inventory#Inventory() 제품없이 초기화하는 함수
*/
Inventory((Collection<Supply> initialSupplies) {
this.supplies = new ArrayList<>(initialSupplies);
}
}무엇보다 중요한 정보는 생성자를 올바르게 호출하는 방법이다.
특히 원하는대로 동작하려면 어떤 전제조건을 충족해야 하는지 알아야 한다.
기본 생성자에는 전제 조건과 입력 매개변수가 전혀 없지만 두 번째 생성자에는 있다.
Supply 객체의 Collection이 initialSupplies를 호출한다.
메서드 매개변수와 마찬가지로 initialSupplies도 설명해야한다.
생성자에는 이름이 없다보니 JavaDoc이 그만큼 중요한 역할을 하고있다.
오늘의 코멘트: 오늘로써 3장이 마무리되었다.
