주석

모든 프로그래머들은 쉽게 이해되는 코드를 작성하기 위해 노력하지만, 종종 부연 설명이 필요할 때도 있습니다. 그런 경우 프로그래머들은 주석(comment) 을 코드에 남겨서, 컴파일러는 이를 무시하지만 코드를 읽는 사람들은 유용한 정보를 얻을 수 있게끔 합니다.

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

// hello, world

러스트에서 주석은 두개의 슬래시로 시작하며, 이 주석은 해당 줄의 끝까지 계속됩니다. 한 줄을 넘기는 주석의 경우에는 아래처럼 각 줄마다 //를 추가하면 됩니다.

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

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

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

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

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

러스트는 문서화 주석(documentation comment) 라고 불리는 또다른 주석 형태를 가지고 있는데, 13장의 ‘Crates.io에 크레이트 배포하기’에서 다루도록 하겠습니다.

주석 작성 실전 기준

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

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

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

주석 품질 점검 기준

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

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

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