주석 작성 가이드

기본 원칙

• 주석은 WHY(왜) 위주로 작성한다. WHAT(무엇)은 코드가 설명해야 한다.
• 당연한 내용을 설명하는 주석은 작성하지 않는다.
• 코드가 명확하면 주석이 필요 없다.
• 주석이 없어도 이해되는 코드가 좋은 코드다.

Javadoc (클래스/메서드)

/**
 * AI 기반 뉴스 다이제스트 생성 서비스.
 *
 * <p>Claude AI를 활용하여 수집된 뉴스 항목을 요약하고
 * 이메일로 발송한다. 배치 스케줄러에 의해 매일 실행된다.</p>
 */
@Service
@RequiredArgsConstructor
public class DigestOrchestrator {

    /**
     * 다이제스트 생성 전체 프로세스를 실행한다.
     *
     * <p>AI 처리 → DB 저장 → 이메일 발송 순서로 실행되며,
     * 실패 시 Slack 알람이 발송된다.</p>
     *
     * @throws IllegalStateException AI 처리 또는 메일 발송 실패 시
     */
    public void runDigest() { ... }
}

인라인 주석 (// )

// 좋은 예 — WHY 설명

// URL 기준 중복 수집 방지를 위해 SHA-256 해시 사용
String fingerprint = FingerprintUtils.sha256(newsUrl);

// 외부 API 호출은 트랜잭션 범위 밖에서 수행 (롤백 불가)
List<DigestNews> digests = aiProcessingService.process();

// 채용 공고는 90일 이내 항목만 유효하다고 판단
LocalDateTime cutoff = LocalDateTime.now().minusDays(90);

// 나쁜 예 — WHAT 설명 (코드가 이미 설명함)

// 리스트 크기를 가져온다
int size = list.size();

// i를 1씩 증가
i++;

// post를 저장
postRepository.save(post);

TODO / FIXME 주석

작업 중 임시로 남기는 주석이지만, 커밋 전 반드시 제거한다.

// TODO: 페이징 처리 추가 필요 (현재 전체 조회)
// FIXME: NullPointerException 발생 가능 — null 체크 추가 필요

• 커밋 시 TODO/FIXME가 남아있지 않도록 확인
• 장기 과제인 경우 GitHub Issues로 관리

th:utext 사용 시 주석

신뢰되지 않은 데이터에 th:utext를 사용할 경우 반드시 사유를 주석으로 명시한다.

<!-- 관리자가 직접 등록한 HTML 콘텐츠, 사용자 입력 아님 -->
<div th:utext="${post.htmlContent}"></div>

주석 달지 않을 상황

코드가 명확할 때는 주석을 달지 않는다:

// 주석 불필요 — 메서드명이 충분히 설명
public PostDetailRes getPost(Long id) {
    return postRepository.findById(id)
            .map(PostDetailRes::from)
            .orElseThrow(() -> new IllegalArgumentException("포스트를 찾을 수 없습니다: " + id));
}

// 주석 불필요 — 변수명이 충분히 설명
boolean isDuplicate = postRepository.existsByTitle(req.getTitle());

체크리스트

• [ ] 주석은 WHY 위주로 작성
• [ ] WHAT 주석 제거 (코드가 설명)
• [ ] 커밋 전 TODO/FIXME 제거 또는 이슈 등록
• [ ] th:utext 사용 시 신뢰 근거 주석 포함
• [ ] 클래스/public 메서드에 Javadoc 작성 (공개 API 수준)