✔ JavaDoc를 공부하게 된 계기
주석작성할때 나름대로 다음 사람에게 인계하는 마음으로 열심히 나름대로 달아놨는데,
최근에 읽은 클린코드책에서는 쓸데없는 주석은 안 다는게 낫다는 말에 주석은 어떻게 써야 잘 쓸수 있는지 고민을 한번 해보는 시간을 갖게 되었다.🤣
JavaDoc란?
아주 간단히 말하면 문서같은 주석(?) /** 내용 */로 시작하는 주석이다.
사전적 정의를 살펴보면 JAVA 소스코드에서 API 문서를 html 태그형식으로 작성하게 해주는 도구이다.
또한, 컴파일시 모든 주석은 지워지므로 프로그램 성능에는 전혀 영향이 없다.
API문서와 같이 annotaion을 이용하여 deparecated, link, Exception 등등의 여러가지 태그를 사용하여 메소드 위에 작성된 주석들을 많이 보았다. (사실 난 이게 JavaDoc를 이용한 주석처리인지 몰랐다...)
참고로, IDE Tool에서 /** Enter를 치면 해당 JavaDoc를 바로 쓸 수 있다.
그렇다면, JavaDoc에서 사용할 수 있는 태그의 종류를 살펴보자!
JavaDoc Tags
JavaDoc에서 사용되는 다양한 태그들을 알아보자.
| annotaion | Description | Example |
|---|---|---|
| @version | 구현체(클래스, 메소드,변수 등)의 버전 | |
| @author | 작성자 | |
| @deprecated | 해당 구현체가 곧 삭제, 업데이트 중단을 의미 | |
| @since | 해당 구현체가 추가된 버전 | |
| @see | 외부 링크나 텍스트, 다른 필드나 메소드를 링크할 때 사용 | 외부 링크 : a href 태그 이용 내부 참조 : 패키지명#생성자/ 필드 / 메소드명 |
| @link | see와 동일한 기능, 참조에 대한 링크 제공 | |
| @exception | 발생할 수 있는 Exception 정의 | |
| @throws | 코드에서 throw 할 수 있는 예외상황 정의 | |
| @param | 메소드의 매개변수 / 인자값 설명 | |
| @return | 반환값 | |
| @serial | Serializable Interface에 사용 | |
| @serialDate | writeObject writeExternal 메소드로 작성된 추가적 데이터를 설명 | |
| @serialField | serialPersistnetFields 배열의 모든 필드에 사용 |
🍔JavaDoc Tag를 이용한 예제
public interface CargoShip {
Stack<Supply> unload();
/**
* {@link Supply}를 싣는다
*
* @param : {@link Queue} 타입의 제품 제공
* @return : {@line Queue} 타입의 적재되지 않은 제품
*/
Queue<Supply> load(Queue<Supply> supplies);
int getRemainingCapacity();
}이런식으로 실제 @param과 @return에 대한 주석을 사용할 수 있다.
사실 이 내용은 이미 메소드만으로도 파악할 수 있어 의미가 없는 내용이다.
그렇다면 우리는 한 단계 더 나아가 실제로 이해할 수 있는 내용을 작성하자!
public interface CargoShip {
Stack<Supply> unload();
/**
* 제품을 화물선에 싣는다.
*
* <p>
* 남은 용량만큼만 제품을 싣게 해준다.
* </p>
*
* @version : 1.0.1
* @author : mhcha
* @param : 적재할 제품이며, null 값은 안됨.
* @return : 용량이 작아 실을 수 없었떤 제품,
* 모두 실었다면 empty
* @throws : 제품이 null -> NullPointException
* @see : CargoShip#getRemainingCapacity()용량 확인하는 함수
* @see : CargoShip#unload() 제품을 내리는 함수
*/
Queue<Supply> load(Queue<Supply> supplies);
int getRemainingCapacity();
}[참조]
JavaDoc 작성하기
자바코딩의 기술 - JavaDoc 예제 - 사이만 하러 저자
JavaDoc이란 무엇이며 문서를 생성하는데 사용하는 방법
Java Web Developer😊