56. 공개된 API 요소에는 항상 문서화 주석을 작성하라
API 문서도 코드만큼 중요하다. Javadoc을 제대로 작성하는 것은 코드 품질의 일부이다.
☕ 1. Javadoc이란?
Java 소스 코드에 작성하는 문서용 주석
이 주석을 바탕으로 자동으로 HTML 문서를 생성할 수 있다
/** ... */을 사용하여 Javadoc 주석 생성
/**
* 이 메서드는 두 수를 더해 결과를 반환합니다.
*
* @param a 첫 번째 정수
* @param b 두 번재 정수
* @return 두 정수의 합
*
*/
public int add(int a, int b){
return a+b;
}1-1. Javadoc의 주요 태그
@param: 매개변수 설명@return: 반환값 설명@throws: 예외가 발생할 수 있음을 설명@see: 관련 항목 참조@deprecated: 더 이상 사용하지 말아야 함
1-2. 잘못된 문서화 vs 올바른 문서화
❌ 잘못된 문서화
/**
* 계산한다.
*/
public int calculate(int a, int b) {
return a + b;
}너무 추상적이다
파라미터와 반환값 설명이 없다
무슨 계산인지 알 수 없다.
🆗 좋은 문서화
/**
* 두 정수의 합을 반환합니다.
* 이 메서드는 null 값을 허용하지 않습니다.
*
* @param a 더할 첫 번째 정수
* @param b 더할 두 번째 정수
* @return a와 b의 합
*/
public int sum(int a, int b) {
return a + b;
}무엇을 하는지(what) 명확히 설명
매개변수와 반환값이 구체적으로 설명됨
제약사항(null 허용 여부 등)도 포함됨
1-3. 그럼 문서화를 왜 해야할끼?
공개 API는 '계약'이다. 개발자는 이 계약에 의존한다.
IDE와 문서 웹 사이트에서 자동으로 보여준다.
단순 주석을 넘어 javadoc은 IntelliJ나 VScode와 같은 IDE에서 자동으로 보여주는 툴팁
Maven이나 Gradle로 build하면 웹페이지 형태의 정식 API 문서도 생성할 수 있음
미래의 나를 위하여
📜 2. 주요 문서화 규약 모음
2-1. Javadoc에는 HTML 태그를 써도 된다!
Javadoc은 HTML로 렌더링 되기 때문에 HTML 태그를 적극적으로 활용 가능합니다
<p>,<pre>,<code>,<ul>등등
/**
* <p>사용자의 정보를 가져옵니다.</p>
*
* <ul>
* <li>이름</li>
* <li>이메일</li>
* </ul>
*
* <pre>{@code
* User user = userService.getUser();
* System.out.println(user.getName());
* }</pre>
*
* @return 사용자 정보 객체
*/
2-2. 주요 문서화 규약 모음
1. 공개된 모든 API 요소에는 문서화 주석을 작성하라
public,protected로 선언된 모든 클래스, 메서드, 필드에는 Javadoc 주석을 반드시 작성private 클래스는 작성 안해도 되지만, API 계약이 되는 부분은 꼭 작성해야 함
/** 이 서비스는 사용자 정보를 반환합니다. */
public interface UserService {
User findById(String id);
}2. API 문서는 "What"을 설명하고, "How"는 피해라
구현 방법을 명시한다
내부 알고리즘이나 DB 구조는 적지 않는다
* 이 메서드는 HashMap을 사용하여 값을... (X)
* 이 메서드는 키에 해당하는 값을 반환합니다. 키가 없으면 null을 반환합니다. (O)3. @param, @return, @throws 태그는 빠짐없이 명확하게
@param: 파라미터 각각 설명(null 허용 여부 포함)@return: 어떤 결과를 반환하는지 설명@throws: 어떤 조건에서 예외가 발생하는지 기술
/**
* 사용자 ID로 사용자 정보를 조회합니다.
*
* @param id 사용자 고유 식별자. null일 수 없습니다.
* @return 사용자 정보 객체
* @throws IllegalArgumentException ID가 null이면 발생
*/4. 제약 조건을 명확히 기술하라라
null 허용 여부
스레드 안전 여부(Thread-safe 여부)
변경 가능 여부(immutable인지 mutable인지)
5. null에 대한 계약도 명확하게 설명하라
인자가 null이 가능한지
반환값이 null일 수 있는지
6. 상속 문서화에는 {@inheritDoc} 또는 @implSpec 활용하기
자바 8부터는
@implSpec태그를 사용하여 구현 세부사항 명시 가능{@inheritDoc}: 부모 클래스의 설명을 그대로 가지고 오고 싶을 때 사용
7. 제네릭의 T와 같은 타입 매개변수도 설명하라
/**
* @param <T> 리스트의 요소 타입
*/
public interface MyList<T> {
void add(T item);
}8. 상수는 의미를 설명하되, 값은 설명하지 말 것
/**
* 최대 사용자 수
*/
public static final int MAX_USERS = 100;
☁️ 3. 백문이불여일견, 직접 생성해보자!
실습 타임!
UTF-8 인코딩 :
-encoding UTF-8 -charset UTF-8
💨 향후 확장 포인트
😺 Javadoc이 잘 작성된 대표 API 예시
1. Java SE 공식 API 문서 🔗 https://docs.oracle.com/javase/8/docs/api/
클래스의 개념 설명
param<E>로 타입 매개 변수 설명메서드마다 입력, 반환값, 예외, 제약조건을 빠짐없이 기술
2. Spring Framework API 🔗 https://docs.spring.io/spring-framework/docs/current/javadoc-api/index.html
어노테이션의 기능 요약 및 내부 동작 설명
@RequestMapping과도 관계를 설명초보자도 언제 쓰는가를 이해할 수 있다
🤖 최종 결론
공개 API에 반드시 Javadoc을 붙이자
@param,@return,@throws는 필수 사용자 관점에서 설명하자자
❗어려웠던 점
자바독을 사용할 일이 많이 없어서 와닿지는 않았는데, 이제 프로젝트를 시작하니 문서 작성을 습관화해야겠다.
😶🌫️ 느낀점
Javadoc 은근 작성하는 것이 재밌을지도?
Last updated