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

1. 너무 추상적이다

2. 파라미터와 반환값 설명이 없다

3. 무슨 계산인지 알 수 없다.

• 🆗 좋은 문서화

/**
 * 두 정수의 합을 반환합니다.
 * 이 메서드는 null 값을 허용하지 않습니다.
 *
 * @param a 더할 첫 번째 정수
 * @param b 더할 두 번째 정수
 * @return a와 b의 합
 */
public int sum(int a, int b) {
    return a + b;
}

1. 무엇을 하는지(what) 명확히 설명

2. 매개변수와 반환값이 구체적으로 설명됨

3. 제약사항(null 허용 여부 등)도 포함됨

1-3. 그럼 문서화를 왜 해야할끼?

1. 공개 API는 '계약'이다. 개발자는 이 계약에 의존한다.

2. IDE와 문서 웹 사이트에서 자동으로 보여준다.

   • 단순 주석을 넘어 javadoc은 IntelliJ나 VScode와 같은 IDE에서 자동으로 보여주는 툴팁

   • Maven이나 Gradle로 build하면 웹페이지 형태의 정식 API 문서도 생성할 수 있음

3. 미래의 나를 위하여

📜 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/

Image

• 클래스의 개념 설명

• param<E>로 타입 매개 변수 설명

• 메서드마다 입력, 반환값, 예외, 제약조건을 빠짐없이 기술

2. Spring Framework API 🔗 https://docs.spring.io/spring-framework/docs/current/javadoc-api/index.html

Image

• 어노테이션의 기능 요약 및 내부 동작 설명

• @RequestMapping과도 관계를 설명

• 초보자도 언제 쓰는가를 이해할 수 있다

---

🤖 최종 결론

공개 API에 반드시 Javadoc을 붙이자@param, @return, @throws는 필수 사용자 관점에서 설명하자자

---

❗어려웠던 점

• 자바독을 사용할 일이 많이 없어서 와닿지는 않았는데, 이제 프로젝트를 시작하니 문서 작성을 습관화해야겠다.

😶‍🌫️ 느낀점

• Javadoc 은근 작성하는 것이 재밌을지도?