🧩 이펙티브 자바 item 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라

1️⃣ 왜 문서화 주석이 중요한가?

자바에서는 /** ... */ 형식의 주석을 JavaDoc 주석이라고 부름

이건 단순한 설명이 아니라,

컴파일러가 인식해서 공식 문서로 변환할 수 있는 API 계약 문서

/**
 * 두 정수의 합을 반환한다.
 *
 * @param a 첫 번째 정수
 * @param b 두 번째 정수
 * @return 두 수의 합
 */
public int sum(int a, int b) {
    return a + b;
}

 

→ javadoc 도구로 자동 HTML 문서 생성 가능

→ IDE에서 마우스 올리면 바로 표시됨

 

2️⃣ “공개된 API”란 무엇인가?

"공개된 API"란 단순히 public만 뜻하지 않음

• 외부에서 사용할 수 있는 모든 요소
  • public 클래스, public 메서드
  • 라이브러리에서 외부에 제공하는 인터페이스, 생성자
  • 다른 팀/모듈에서 참조할 가능성이 있는 public API

즉, 내 코드가 다른 개발자에게 노출되는 순간부터는

문서화 주석이 계약의 일부가 됨

 

3️⃣ 문서화 주석의 기본 구조

태그	역할	예시
@param	매개변수 설명	@param count 처리할 항목 개수
@return	반환값 설명	@return 계산 결과 값
@throws	예외 설명	@throws NPE 입력이 null인 경우
@see	관련 문서/메서드 링크	@see Math#sqrt(double)
@implSpec	구현 시 주의사항	@implSpec 내부적으로 캐시를 사용함
@since	도입 버전	@since 1.8

 

4️⃣ 좋은 JavaDoc의 핵심 원칙

✅ (1) 문서는 “무엇을 하는지”에 집중하라

/**
 * 주어진 키의 값을 반환한다.
 * 키가 존재하지 않으면 null을 반환한다.
 */
public V get(Object key);

 

좋은 예시: "무엇을 하는가"

나쁜 예시: "어떻게 하는가"

 

✅ (2) 계약(Contract)을 명확히 기술하라

• 어떤 입력값이 허용되는가?
• null이 허용되는가?
• 스레드 안전한가?
• 부작용이 있는가?

/**
 * 이 메서드는 스레드에 안전하지 않다.
 * 외부에서 동기화를 보장해야 한다.
 */

 

✅ (3) 예외 조건을 꼭 적어라

/**
 * @throws IllegalArgumentException 입력값이 음수인 경우
 */

 

API 사용자 입장에서는 어떤 상황에서 예외가 나는지를 아는 게

"어떻게 써야 하는가"보다 훨씬 중요함

 

✅ (4) null 반환, Optional, 불변성 여부 명시

/**
 * @return 찾은 사용자. 없으면 Optional.empty() 반환
 */
public Optional<User> findById(long id);

 

명시하지 않으면 사용자는 null 체크를 해야 할지 헷랄림

 

✅ (5) 상속 메서드는 {@inheritDoc} 태그로 연결

/**
 * {@inheritDoc}
 * 추가로, 이 구현은 캐싱을 사용한다.
 */
@Override
public double calculate(int x) { ... }

 

부모 문서를 그대로 상속하면서 일부 내용만 보강할 수 있음 

 

5️⃣ 예시: 문서화된 클래스 전체

/**
 * 간단한 계산기를 나타낸다.
 * 이 클래스는 불변(immutable)이다.
 *
 * @author SungHyun
 * @since 1.0
 */
public final class Calculator {

    /**
     * 두 정수를 더한다.
     *
     * @param a 첫 번째 피연산자
     * @param b 두 번째 피연산자
     * @return 두 수의 합
     */
    public int add(int a, int b) {
        return a + b;
    }

    /**
     * 0으로 나누면 ArithmeticException을 던진다.
     *
     * @throws ArithmeticException 0으로 나누는 경우
     */
    public int divide(int a, int b) {
        return a / b;
    }
}

 

6️⃣ 실무 팁 — 팀/프로젝트에서 JavaDoc 관리하기

상황	팁
DTO, VO	필수는 아님(단순 데이터)
Service / API	✅ 반드시 작성(계약의 핵심)
Public Utility 클래스	✅ 작성 필수
Private 내부 메서드	선택 (필요 시 일반 주석 //로 충분)