주석

모든 프로그래머는 쉽게 이해되는 코드를 작성하기 위해 노력하지만, 종종 부연 설명이 필요할 때도 있습니다.

그런 경우 프로그래머는 주석(comment)을 코드에 남깁니다. 일반 주석은 렉싱 과정에서 공백처럼 취급되므로 프로그램의 토큰이 되지 않지만, 코드를 읽는 사람에게는 유용한 맥락을 제공합니다. 문서화 주석은 이와 달리 doc 속성으로 해석됩니다.

간단한 주석의 예를 봅시다.

// hello, world

러스트의 한 줄 일반 주석은 두 개의 슬래시 //로 시작하며 줄 바꿈이나 파일의 끝까지 계속됩니다.

한 줄을 넘기는 주석의 경우에는 아래처럼 각 줄마다 //를 추가하면 됩니다.

// 그래서 여기서는 여러 줄의 주석을 달 필요가 있을 정도로
// 복잡한 작업을 하고 있습니다. 이 주석으로 무슨 일이
// 일어나고 있는지 설명할 수 있습니다.

또한 주석은 코드의 뒷부분에 위치할 수도 있습니다.

fn main() {
    let lucky_number = 7; // 오늘 운이 좋은 느낌이에요
}

하지만 아래와 같이 코드 앞줄에 따로 주석을 작성한 형태를 더 자주 보게 될 겁니다.

fn main() {
    // 오늘 운이 좋은 느낌이에요
    let lucky_number = 7;
}

블록 일반 주석은 /*와 */ 사이에 작성합니다. Rust의 블록 주석은 중첩할 수 있으므로, 바깥 주석 안에 또 다른 블록 주석을 둘 수 있습니다.

/* 바깥 주석
   /* 중첩된 주석 */
   다시 바깥 주석
*/

문서화 주석과 속성

Rust의 문서화 주석(documentation comment)은 일반 주석처럼 버려지지 않습니다.

• 정확히 세 개의 슬래시로 시작하는 ///와 /** ... */는 바깥쪽 문서화 주석입니다. 각각 #[doc = "..."] 형태의 바깥쪽 속성으로 해석되어 뒤따르는 항목처럼 바깥쪽 속성을 받을 수 있는 대상에 적용됩니다. ////와 /*** ... */는 바깥쪽 문서화 주석이 아니라 일반 주석입니다.
• //!와 /*! ... */는 안쪽 문서화 주석입니다. 각각 #![doc = "..."] 형태의 안쪽 속성으로 해석되어 자신을 포함하는 크레이트나 모듈 같은 대상에 적용됩니다.

문서화 주석에는 관례상 Markdown을 작성하고 rustdoc이 이를 문서로 렌더링합니다. 다만 주석 문법 자체가 Markdown을 이해하는 것은 아닙니다. 예를 들어 Markdown 코드 조각 안에서도 */는 블록 주석의 닫힘 기호로 처리됩니다. 문서화 주석의 활용은 13장의 ‘Crates.io에 크레이트 배포하기’에서 더 자세히 다룹니다.

소스 파일 맨 앞 또는 선택적 바이트 순서 표시(BOM) 바로 뒤의 shebang(#!...)도 주석과 구분해야 합니다. #! 뒤에서 공백과 일반 주석을 건너뛴 다음 [가 나오지 않는 첫 줄은 shebang으로 인식되어 토큰화 전에 입력에서 제거됩니다. 반면 #![...]는 안쪽 속성입니다.

// 줄 바꿈 또는 EOF까지
/* 바깥 /* 중첩 */ 계속 */

/// 실행 계약
/** 추가 설명 */
pub fn run() {}

//! 크레이트 안내
/*! 모듈 안내 */

주석 작성 실전 기준

주석은 코드의 동작을 반복 설명하기보다, 코드만으로 드러나지 않는 의도와 제약을 기록할 때 가장 효과적입니다.

• 왜 이 구현을 선택했는지(대안 대비 이유)를 남깁니다.
• 경계값 처리, 안전성 전제, 성능 타협 지점을 짧게 기록합니다.
• 구현이 바뀌면 주석도 즉시 업데이트해 코드와 문서 불일치를 방지합니다.

이 원칙을 지키면 주석은 읽는 비용이 낮고 유지보수에 직접 도움이 되는 문서가 됩니다.

주석 품질 점검 기준

코드 리뷰 단계에서는 주석이 있는지보다 주석이 정확한지를 먼저 확인해야 합니다.

• 코드가 바뀌었는데 주석이 예전 동작을 설명하고 있지 않은지 점검합니다.
• 주석이 구현을 그대로 반복하고 있다면, 필요한 이유 설명으로 바꾸거나 삭제합니다.
• 함수 경계에서 실패 조건, 입력 제약, 안전성 가정이 누락되지 않았는지 확인합니다.

이 기준을 적용하면 주석은 단순 메모가 아니라 유지보수 리스크를 줄이는 문서 역할을 수행합니다.

예시 변수명과 코드만으로 알 수 있는 곱셈을 되풀이하기보다, 왜 60을 곱하는지 남겨 봅시다. 아래는 다른 예제와 별개로 실행하는 완전한 프로그램입니다.

fn main() {
    let minutes = 3;
    // 저장 형식이 초 단위이므로 분을 초로 바꾼다.
    let seconds = minutes * 60;
    println!("{seconds}");
}

예상 출력은 180입니다. 주석은 Rust의 계산 규칙을 바꾸지 않으며, 사람이 입력 단위와 저장 형식의 약속을 확인하게 합니다.

스스로 확인하기 minutes만 4로 바꾸면 출력과 주석은 어떻게 되나요? 이어 곱하는 수만 100으로 바꾸고 주석을 그대로 두었을 때, 400이라는 실행 결과가 주석의 정확성을 증명하는지도 판단해 보세요.