반응형
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 내부 메서드 | 선택 (필요 시 일반 주석 //로 충분) |
반응형
'Java & Spring Boot' 카테고리의 다른 글
| 🧩 도메인 vs 도메인 서비스 vs 애플리케이션 서비스 (0) | 2025.12.02 |
|---|---|
| 🔄 순환 참조, 왜 생기고 어떻게 끊어야 할까 (0) | 2025.11.28 |
| ⚙️ 이펙티브 자바 item 48. 스트림 병렬화는 주의해서 사용하라 (0) | 2025.10.22 |
| 🧩 이펙티브 자바 item 41. 정의하려는 것이 타입이라면 마커 인터페이스를 사용하라 (0) | 2025.10.21 |
| 🧩 이펙티브 자바 item 31. 한정적 와일드카드로 API 유연성을 높이라 (0) | 2025.10.17 |