C++ 주석 작성 규칙¶

상태: 채택 · 적용 범위: C++ 소스의 설명 주석과 공개 API 문서 주석 · 예제: C++11 이상

주석은 이름과 코드만으로 알기 어려운 의도·제약·사용 조건을 설명한다. 코드가 이미 명확히 표현한 내용을 반복하지 않는다.

핵심 규칙¶

상황	작성 기준	강도
일반 설명	한국어로 작성하고 식별자·API·기술 용어는 원래 표기 유지	필수
구현 설명	비직관적인 이유와 제약을 해당 코드 위에 `//`로 작성	권장
공개 API	이름·타입만으로 알 수 없는 호출 계약을 선언 위치에서 설명	필수
API 주석 형식	문서화할 공개 API는 `///`, 일반 구현 설명은 `//`	필수
자명한 코드	동작을 그대로 반복하는 주석 생략	권장
TODO·FIXME	해결할 문제와 완료 조건을 구체적으로 작성	필수
코드 변경	영향을 받는 주석도 함께 수정	필수

들여쓰기·줄 길이·파일 인코딩은 코드 포맷 규칙을 따른다. 식별자 개선으로 해결할 수 있는 설명은 명명 규칙에 맞춰 코드에 반영한다.

구현 주석: 이유와 제약¶

알고리즘의 비직관적인 선택, 호출 순서의 이유, 단위, 특수값, 외부 시스템 제약 등 코드만으로 알기 어려운 정보를 남긴다. 길어지는 설명은 여러 줄의 //로 나눈다.

// 피할 주석: 코드에 보이는 연산만 반복한다.
// count를 1 증가시킨다.
// ++count;

아래는 캐시에서 음수를 “만료 시각 없음”으로 정의한 상황의 예다. 음수의 의미가 함수 이름만으로 드러나지 않으므로 설명한다.

bool IsExpired(
    int expiryTick,
    int currentTick)
{
    // 음수는 만료 시각이 없는 항목이므로 시간 비교에서 제외한다.
    if (expiryTick < 0)
    {
        return false;
    }

    return currentTick >= expiryTick;
}

성능을 이유로 선택한 코드에는 측정 환경이나 근거 문서 링크를 남긴다. 측정하지 않은 수치나 “항상 빠르다”는 단정은 쓰지 않는다.

공개 API: 호출 계약¶

구현을 읽지 않고 호출할 수 있도록 다음 중 필요한 내용을 선언 위치에 작성한다.

입력의 의미·단위·허용 범위와 사전 조건.
반환값과 실패 시 동작, 출력 인자의 변경 여부.
참조·포인터의 소유권과 유효 기간.
호출 순서와 스레드 관련 제약.

헤더의 공개 API 문서에는 /// 형식을 사용한다. 각 설명 줄을 ///로 시작하고, @brief에는 목적을 짧게 적는다. @param, @return, @note 등은 실제로 설명할 정보가 있을 때 추가한다. void 함수에 빈 @return을 붙이는 등 형식만 채우지 않는다. 문서 생성 도구의 사용 여부와 관계없이 같은 형식을 유지한다.

/// @brief 설정 파일을 읽어 기존 설정을 교체한다.
/// @param filePath UTF-8 경로. nullptr를 허용하지 않는다.
/// @return 성공 시 true. 실패 시 false이며 기존 설정은 유지된다.
bool LoadSettings(const char* filePath);

위 예시는 계약을 설명하는 선언이다. 실제 구현이 이 동작을 보장할 때만 같은 주석을 작성한다.

자명한 Getter·Setter나 계약을 그대로 따르는 재정의 함수는 설명을 생략할 수 있다. 단, 부작용·실패 조건·수명 제약이 있다면 이름이 단순해도 문서화한다. 상속받은 계약은 중복 복사하지 않고 차이만 설명한다.

선언에는 호출 계약, 정의에는 구현 이유를 둔다. 헤더에 구현하는 함수도 같은 설명을 두 번 작성하지 않는다. private 헬퍼에도 비직관적인 동작이 있으면 일반 구현 주석을 남긴다.

TODO와 FIXME¶

TODO: 아직 구현하지 않은 작업이나 개선 사항.
FIXME: 확인된 결함이나 잘못된 동작.
추적 이슈가 있으면 식별자나 링크를 추가한다. 없는 이슈 번호는 만들지 않는다.
“나중에 수정” 대신 무엇을 바꾸면 완료인지 적는다. 임시 우회라면 제거 조건을 남긴다.

// TODO: 설정 파일의 버전 필드를 읽고 지원하지 않는 버전은 거부한다.
// FIXME: 빈 파일 입력에서 기존 설정이 초기화되는 문제를 수정한다.

예제 주석은 작성 형식을 보여주며 이 저장소에 실제로 존재하는 결함이나 할 일을 뜻하지 않는다. 우선순위·담당자·일정은 추적 이슈에 기록하고 주석에는 필요한 연결 정보만 둔다.

유지보수와 예외¶

동작·입력·수명이 바뀌면 관련 주석을 같은 변경에서 갱신한다.
사용하지 않는 코드를 주석 처리해 장기간 보관하지 않는다. 과거 구현은 버전 이력으로 확인한다.
주석에 규칙 전문을 반복하지 않는다. 설명이 길면 설계 문서나 해당 위키 항목을 연결한다.
문서 생성 도구의 도입과 설정, 추가 태그 체계는 후속 작업으로 둔다.

근거와 출처¶

기존 정리본（로컬 참고 자료）의 한국어 주석, 이유 중심 설명, 공개 API의 문서 태그를 바탕으로 작성했다. 사용자 선택에 따라 API 주석은 기존 블록 형식에서 ///로 변경했다. 모든 API에 태그를 채우는 방식은 필요한 계약만 작성하도록 구체화했다. 기존의 다양한 작업 태그와 우선순위 표기는 이번 정리에서 TODO·FIXME 중심으로 단순화했다.

Google의 선언·정의 설명 분리와 자명한 주석 생략 원칙을 참고했다. 한국어와 Doxygen 표기는 기존 개인 스타일이며 Google 전체 정책의 채택을 뜻하지 않는다. Google은 TODO에 추적 식별자를 요구하지만 이 문서는 이슈가 없는 개인 작업도 구체적인 완료 조건으로 기록할 수 있게 한다.

출처 확인일: 2026-09-12.

채택일: 2026-09-12. 명시된 적용 범위 안에서 채택하며, 후속 정리 대상은 제외한다.