주석 가이드

기본 원칙

• 코드를 읽으면 알 수 있는 내용은 주석 금지 (노이즈)
• 왜(Why) 이렇게 했는지 설명하는 주석 작성
• 무엇을(What) 하는지는 코드 자체로 표현
• 공개 API (public 메서드/클래스)는 JavaDoc 필수

클래스 주석

클래스 주석은 /** ... */ 형식으로 작성하며, 어노테이션 위에 위치한다.

/**
 * 사용자 관련 비즈니스 로직을 처리하는 서비스 클래스.
 *
 * <p>사용자 등록, 조회, 수정, 삭제 기능을 제공한다.
 * 모든 쓰기 작업은 트랜잭션으로 처리된다.</p>
 *
 * @author 홍길동
 * @since 2026-05
 */
@Service
@RequiredArgsConstructor
@Slf4j
public class UserService {
    // ...
}

메서드 주석

메서드 주석에는 @param, @return, @throws를 포함한다.

/**
 * 사용자 단건 조회.
 *
 * <p>사용자 일련번호로 사용자 정보를 조회한다.</p>
 *
 * @param vo 조회 조건 (userSn 필수)
 * @return 사용자 정보, 존재하지 않으면 null
 * @throws BusinessException 사용자를 찾을 수 없는 경우
 */
@Transactional(readOnly = true)
public UserVo get(UserVo vo) {
    UserVo result = userMapper.get(vo);
    if (result == null) {
        throw new UserNotFoundException(vo.getUserSn());
    }
    return result;
}

/**
 * 사용자 등록.
 *
 * @param vo 등록할 사용자 정보
 * @throws DuplicateUserIdException 아이디 중복 시
 */
@Transactional(rollbackFor = Exception.class)
public void regist(UserVo vo) {
    // ...
}

JavaDoc 필수 대상

코드 라인 주석

코드 라인 주석은 // 사용하며, 개발 의도를 설명한다.

@PostConstruct
public void init() {
    // @PostConstruct: 의존성 주입 완료 후 1회 실행
    // 파일 스캔은 시간이 걸릴 수 있으므로 캐시에 미리 로딩
    loadAllDocs();
}

public String processApiKey(String apiKey) {
    // API 키가 없으면 즉시 반환 (외부 호출 방지)
    if (StringUtil.isEmpty(apiKey)) {
        return null;
    }

    // pageContent는 최대 3000자로 제한 (토큰 비용 절약)
    String truncated = pageContent.length() > 3000
            ? pageContent.substring(0, 3000)
            : pageContent;
    // ...
}

금지 패턴

// 나쁜 예 — 코드와 동일한 내용 반복 (노이즈)
int count = 0;  // count를 0으로 초기화

// 나쁜 예 — 오래된 주석 (코드와 불일치)
// userId로 조회 (실제로는 userSn으로 변경됨)
UserVo result = userMapper.getByUserSn(userSn);

// 나쁜 예 — 코드 주석 처리 (삭제해야 함)
// userService.oldMethod(vo);
userService.newMethod(vo);

TODO / FIXME 주석

// TODO: [2026-06] 사용자 캐시 자동 갱신 기능 추가
// 현재는 수동 삭제 후 재조회 필요

// FIXME: [2026-05] null 체크 누락 — NPE 가능성
// userSn이 null일 때 처리 필요

// HACK: 외부 API 응답 형식이 일정하지 않아 임시 처리
// 외부 API 수정 후 제거 예정

보안 관련 주석

보안 예외 처리 시 이유를 명시한다.

<!-- 서버에서 렌더링된 마크다운 HTML, 사용자 입력 아님 -->
<!-- th:utext 허용: 관리자가 관리하는 내부 콘텐츠 -->
<div th:utext="${doc.htmlContent}"></div>

체크리스트

• [ ] public 클래스/메서드에 JavaDoc 작성
• [ ] 어노테이션 위에 클래스 주석 위치
• [ ] @param, @return, @throws 태그 포함
• [ ] "왜(Why)" 설명 중심 주석
• [ ] 코드와 불일치하는 주석 즉시 삭제
• [ ] 주석 처리된 코드 삭제 (버전 관리는 git 사용)
• [ ] TODO/FIXME 작성 시 날짜 명시