주석 | Rust - 안동민 개발노트

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

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

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

// hello, world

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

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

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

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

src/main.rs

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

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

src/main.rs

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

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

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

문서화 주석과 속성

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

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

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

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

LEXICAL BOUNDARY

겉모양이 비슷해도 모두 “컴파일러가 무시하는 메모”는 아닙니다. 표기별로 렉서 이후의 의미가 갈립니다.

일반 주석 · 공백으로 취급

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

// 한 줄 주석과 /* ... */ 블록 주석은 토큰화 과정에서 공백처럼 해석됩니다. 블록 주석은 중첩할 수 있습니다.

////와 /***…*/는 문서화 주석이 아니라 일반 주석입니다.

바깥쪽 문서 · 다음 대상

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

#[doc = "..."]

바깥쪽 doc 속성으로 해석되어 뒤따르는 항목 등 바깥쪽 속성을 받을 수 있는 대상에 적용됩니다.

안쪽 문서 · 포함하는 대상

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

#![doc = "..."]

안쪽 doc 속성으로 해석되어 자신을 포함하는 크레이트나 모듈 같은 대상에 적용됩니다.

문서화 주석은 Markdown 문서 입력이다

컴파일러는 문서화 주석을 단순히 버리지 않고 doc 속성으로 처리합니다. 그 텍스트는 관례상 Markdown이며 rustdoc이 렌더링합니다. 그러나 주석 문법 자체는 Markdown을 해석하지 않으므로 블록 안의 */는 문맥과 관계없이 주석을 끝냅니다.

#![...]는 안쪽 속성입니다. 반면 파일 선두(선택적 BOM 바로 뒤)의 shebang은 주석이 아니며, #! 뒤의 다음 비공백·비일반-주석 토큰이 [가 아니면 해당 첫 줄을 토큰화 전에 제거합니다. 작성할 주석에는 코드가 드러내지 못한 이유와 제약을 남기고 구현과 함께 갱신합니다.

주석 작성 실전 기준

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

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

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

주석 품질 점검 기준

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

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

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

주석