C++ 주석 작성 규칙¶

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

주석은 코드에 드러나지 않는 의도·제약·호출 계약을 설명한다.

핵심 규칙¶

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

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

구현 주석: 이유와 제약¶

알고리즘·호출 순서의 이유, 단위·특수값·외부 제약을 //로 설명한다. 긴 설명은 여러 줄로 나눈다.

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

    return currentTick >= expiryTick;
}

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

공개 API: 호출 계약¶

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

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

문서 생성 도구와 무관하게 각 줄에 ///를 사용한다. @brief에는 목적을, @param·@return·@note에는 필요한 정보만 적는다. 빈 태그를 채우지 않는다.

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

API 주석은 실제 구현이 보장하는 계약과 일치시킨다.

자명한 Getter·Setter·재정의는 설명을 생략할 수 있다. 부작용·실패·수명 제약은 문서화하고 상속 계약은 차이만 적는다.

선언에는 계약, 정의에는 구현 이유를 둔다. 헤더 구현에서도 중복하지 않으며 private 헬퍼의 비직관적 동작은 //로 설명한다.

TODO와 FIXME¶

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

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

예시는 실제 할 일·결함 기록이 아니다. 우선순위·담당자·일정은 이슈에, 주석에는 연결 정보만 둔다.

유지보수와 예외¶

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

근거와 출처¶

기존 정리본（로컬 참고 자료）의 한국어·이유 중심 주석을 유지하되 API는 ///·필요한 태그, 작업 기록은 TODO·FIXME로 구체화했다.

Google의 선언·정의 분리와 자명한 설명 생략을 참고했다. 한국어·Doxygen 표기와 이슈 없이 완료 조건을 적는 TODO는 개인 선택이며, Google은 TODO 식별자를 요구한다.

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

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

변경 기록¶

2026-10-16: 반복 설명·중복 예시·배경을 줄여 핵심 규칙과 예시 중심으로 정리했다. 규칙 강도·예외·버전과 채택·초안·미결정 상태는 유지했다.