Javadoc: 코드를 제품으로 격상시키는 문서화의 기술

게시 2026/04/01

By woolam

조회 6 분읽는 시간

“한 줄 요약: 주석이 ‘어떻게(How)’에 집중한다면, Javadoc은 ‘무엇을(What)’과 ‘왜(Why)’라는 계약에 집중한다.”

1. Javadoc은 왜 필요할까?

단순히 “설명이 필요해서”가 아니다. 잘 작성된 Javadoc은 다음과 같은 강력한 이점을 제공한다.

API 계약의 명시: 메서드가 무엇을 입력받고 무엇을 반환하며 어떤 예외를 던지는지 명확히 정의함으로써 사용자(동료 또는 미래의 나)에게 코드 사용의 확신을 준다.
IDE의 즉각적인 지원: IntelliJ와 같은 IDE에서 코드 위에 마우스를 올리기만 해도 나타나는 툴팁은 개발 흐름을 끊지 않고 핵심 정보를 전달한다.
문서 자동화: javadoc 도구를 통해 소스 코드에서 HTML 형태의 공식 문서를 추출할 수 있어서 라이브러리나 대규모 프로젝트의 가이드를 쉽게 제작할 수 있다.
유지보수 비용 감소: 구현 세부사항이 아닌 ‘의도’를 기록하므로 내부 로직이 변경되더라도 외부 사용자가 참고해야 할 문서는 안정적으로 유지된다.

2. 어떻게 작성해야할까?

Javadoc은 /**로 시작하여 */로 끝나는 블록 주석 내부에 작성한다.

2-1. 작성 예시

  
/**
 * 첫 번째 문장은 메서드의 기능을 요약한 요약문이다.
 * 마침표(.)를 기준으로 요약문이 결정되므로 신중하게 작성한다.
 *
 * @param productId 조회할 상품의 고유 ID (null 불가)
 * @return 조회된 상품 객체 해당 상품이 없으면 Optional.empty() 반환
 * @throws IllegalArgumentException ID 형식이 잘못된 경우 발생
 */
public Optional<Product> findProductById(String productId) {
    // logic...
}

2-2. 주요 태그 활용법

Javadoc에서 자주 사용되는 핵심 태그와 그 의미를 정리하면 다음과 같다.

태그	의미	활용 팁
@param	매개변수 설명	변수명 뒤에 설명을 붙인다. 제약 조건을 포함하면 좋다.
@return	반환값 설명	반환되는 데이터의 의미와 특이사항을 명시한다.
@throws	예외 설명	어떤 상황에서 어떤 비즈니스 예외나 런타임 예외가 발생하는지 적는다.
{@link}	인라인 링크	설명 도중 다른 클래스나 메서드를 참조할 때 클릭 가능한 링크를 만든다.
{@code}	코드 포맷	텍스트를 코드 스타일로 렌더링하며 HTML 특수문자 처리를 대신해준다.

3. 실무적인 작성 팁

더 나은 문서를 작성하기 위해 다음 세 가지 원칙을 기억해야 한다.

요약문은 간결하게: 첫 문장만 봐도 메서드의 목적을 알 수 있어야 한다. Javadoc 요약 페이지에는 첫 마침표(.) 전까지의 문장만 노출되기 때문이다.
구현은 숨기고 의도는 드러내라: “for문을 돌려 리스트를 합산함”과 같은 구현 방식이 아니라 “주문 항목의 총 금액을 계산함”과 같이 비즈니스적 의도(What) 를 적어야 한다.
불필요한 중복 제거: 메서드 이름만으로 의미가 100% 전달되는 명확한 코드라면 굳이 뻔한 내용을 적어 읽는 이에게 노이즈를 제공하지 않는다.

4. 회고: 코드 그 이상의 가치를 만드는 훈련

오늘 Javadoc에 대해 깊이 있게 정리하며 느낀 점은 문서화가 단순히 ‘글쓰기’가 아니라 ‘설계의 완성’ 이라는 점이다.

반성의 점: 그동안 코드를 짜는 데만 급급해 내가 만든 메서드가 다른 사람에게 어떻게 보일지 고민하는 시간이 부족했다.
훈련 계획: 앞으로는 모든 메서드와 인터페이스에 최소한 @param과 @return은 포함하는 Javadoc 작성을 습관화할 것이다.
다짐: 단순히 돌아가는 코드가 아니라 누구나 쉽게 읽고 안전하게 쓸 수 있는 ‘제품으로서의 코드’ 를 만드는 개발자가 되기 위해 꾸준히 기록하고 훈련해야겠다.

5. 참고 문서 (References)

본 포스팅은 다음의 신뢰할 수 있는 가이드를 참고하여 작성하였습니다.

Oracle Official Guide: How to Write Doc Comments for the Javadoc Tool
Google Java Style Guide: Section 7 - Javadoc
Joshua Bloch: Effective Java (3rd Edition) - Item 56: “공개된 API 요소에는 모두 문서화 주석을 달아라”

Java, Documentation