154 lines
5.3 KiB
Markdown
154 lines
5.3 KiB
Markdown
# Javadoc 작성 / 수정 / 삭제 기준
|
|
|
|
## 목적
|
|
|
|
Javadoc은 코드 설명서가 아니라 **API 계약과 오해 가능성이 있는 의미를 문서화하는 도구**로 사용한다.
|
|
“코드를 읽으면 바로 아는 내용”을 반복하지 않는다.
|
|
|
|
## 공식 의미
|
|
|
|
- Javadoc doc comment는 선언 바로 앞에 있어야 인식된다.
|
|
- 한 doc comment는 설명(description)과 block tags로 구성된다.
|
|
- 첫 요약 문장은 summary/index에 재사용되므로 특히 중요하다.
|
|
- override/implement 메서드는 자체 문서가 없으면 상위 문서를 상속할 수 있다.
|
|
- visible한 class/member에는 Javadoc이 있는 것이 기본이지만, 정말 단순하고 obvious한 경우나 override는 예외가 될 수 있다.
|
|
|
|
## 기본 규칙
|
|
|
|
### 1. Javadoc은 계약을 문서화할 때만 쓴다
|
|
다음 중 하나가 있으면 Javadoc을 작성한다.
|
|
|
|
- public/protected API
|
|
- 외부 모듈이 호출하는 계약
|
|
- null 허용 여부가 중요함
|
|
- 예외 조건/전제조건/후조건이 중요함
|
|
- thread-safety, side effect, state change가 중요함
|
|
- 경계 조건이나 corner case를 안 쓰면 오해할 수 있음
|
|
- 이름만으로는 의미가 충분하지 않음
|
|
|
|
### 2. “코드를 읽으면 아는 내용”은 쓰지 않는다
|
|
다음은 기본 금지한다.
|
|
|
|
- getter/setter를 그대로 풀어쓴 설명
|
|
- 필드명/파라미터명을 문장으로 반복
|
|
- 구현을 한 줄씩 설명하는 Javadoc
|
|
- 리팩터링 후 쉽게 stale 해질 정보
|
|
|
|
금지 예:
|
|
- `Returns the user name.` 만 있는 자명한 `getUserName()`
|
|
- `Sets the value.` 같은 설명
|
|
|
|
### 3. 첫 줄은 summary로 쓴다
|
|
Javadoc 첫 줄은 짧고 독립적으로 읽히는 요약이어야 한다.
|
|
|
|
기본:
|
|
- 요약 1줄
|
|
- 필요한 경우 상세 설명
|
|
- 그 후 block tags
|
|
|
|
### 4. 구현 세부보다 호출 계약을 우선
|
|
Javadoc은 아래를 더 우선해서 쓴다.
|
|
|
|
- 무엇을 보장하는가
|
|
- 어떤 입력이 허용되는가
|
|
- 어떤 경우 실패하는가
|
|
- 호출자가 믿어도 되는 동작은 무엇인가
|
|
- 반환값의 의미는 무엇인가
|
|
|
|
다음은 기본 지양한다.
|
|
- 내부 알고리즘 설명
|
|
- 현재 구현 방식
|
|
- 성능 미세 최적화 세부
|
|
|
|
### 5. `@param`, `@return`, `@throws`는 의미가 있을 때만 정확히 쓴다
|
|
태그를 채우기 위한 태그를 금지한다.
|
|
|
|
기본:
|
|
- `@param`: 파라미터 의미/제약/허용 범위/nullable 여부
|
|
- `@return`: 반환값 의미, empty/optional/null/ordering/ownership
|
|
- `@throws`: 실제 계약상 중요한 예외 조건
|
|
|
|
### 6. 예외 문서는 “언제 왜 던지는가”를 쓴다
|
|
단순히 예외 타입만 나열하지 않는다.
|
|
|
|
좋은 방향:
|
|
- 어떤 입력/상태에서
|
|
- 어떤 이유로
|
|
- 호출자가 무엇을 기대해야 하는지
|
|
|
|
### 7. self-explanatory 멤버는 Javadoc 생략 가능
|
|
정말 단순하고 obvious한 멤버는 Javadoc을 생략할 수 있다.
|
|
|
|
예:
|
|
- 의미가 완전히 자명한 getter
|
|
- record component 중 이름만으로 충분한 경우
|
|
|
|
단, typical reader가 모를 수 있는 의미가 있으면 생략하지 않는다.
|
|
|
|
### 8. override는 상속 문서를 우선 활용
|
|
override/implement 메서드에서 상위 문서가 충분하면 Javadoc을 반복하지 않는다.
|
|
|
|
다만 아래 경우에는 다시 쓴다.
|
|
- 하위 타입에서 계약이 추가됨
|
|
- 예외/부작용/동시성 보장이 달라짐
|
|
- 더 좁은 의미가 생김
|
|
|
|
### 9. Javadoc과 코드가 어긋나면 Javadoc이 잘못된 것
|
|
코드가 바뀌면 Javadoc도 같이 수정한다.
|
|
맞출 수 없으면 지운다.
|
|
|
|
기본 규칙:
|
|
- stale Javadoc 금지
|
|
- 애매한 Javadoc보다 없는 편이 낫다
|
|
- 거짓 문서 금지
|
|
|
|
### 10. Javadoc은 boundary/API 중심으로 우선 배치
|
|
프로젝트에서는 아래 우선순위로 작성한다.
|
|
|
|
1. public/protected API
|
|
2. 외부 호출되는 application/presentation boundary
|
|
3. 의미가 어려운 domain type / value object
|
|
4. 예외/정책/동시성 규약이 중요한 infrastructure API
|
|
5. package-level overview가 필요한 package
|
|
|
|
### 11. implementation comment로 계약을 설명하지 않는다
|
|
class/member의 전체 목적이나 호출 계약을 설명하는 내용이면 `//` 주석 대신 Javadoc으로 쓴다.
|
|
|
|
### 12. package/class level Javadoc은 구조 설명에 사용
|
|
package/class 수준에서는:
|
|
- 목적
|
|
- 포함 내용
|
|
- 관계
|
|
- 사용 시 주의점
|
|
- 외부 문서 링크
|
|
를 설명할 수 있다.
|
|
|
|
긴 설명은 외부 architecture/spec 문서로 분리하고 링크한다.
|
|
|
|
### 13. 한 줄 Javadoc은 정말 짧을 때만
|
|
한 줄로 끝나는 Javadoc은:
|
|
- 매우 짧고
|
|
- block tag가 없고
|
|
- 요약만으로 충분할 때만 사용한다
|
|
|
|
### 14. 포맷보다 의미를 우선하되 형식은 일관되게
|
|
기본 형식:
|
|
- summary
|
|
- 빈 줄
|
|
- 상세 설명 (필요 시)
|
|
- block tags (`@param`, `@return`, `@throws`, `@deprecated` 순)
|
|
|
|
### 15. Javadoc은 examples보다 계약 우선
|
|
examples/tutorial 성격의 설명은 docs/examples나 외부 문서가 더 적합할 수 있다.
|
|
Javadoc은 먼저 API contract를 충실히 담는다.
|
|
|
|
## 프로젝트 기준 요약
|
|
|
|
- Javadoc은 계약/제약/의미를 문서화할 때만 작성
|
|
- 자명한 설명, 구현 반복 설명 금지
|
|
- 첫 줄 summary 필수
|
|
- `@param/@return/@throws`는 의미 있을 때만 정확히 작성
|
|
- self-explanatory 멤버와 override는 생략 가능
|
|
- stale Javadoc 금지
|
|
- 맞출 수 없으면 수정하거나 삭제
|