주석과 문서 주석
Rust에서 주석은 코드의 흐름에 영향을 주지 않고 개발자가 코드의 의도나 동작을 설명하기 위해 사용하는 구조이다. 일반적인 주석은 컴파일러나 런타임 시점에 무시되므로 실행 성능에 영향을 주지 않는다. 다만 주석이 없는 소스 코드는 이해하기 어렵고 유지보수가 힘들어질 수 있으므로, 적절히 주석을 추가하여 코드를 명확하게 설명하는 습관을 들이는 것이 좋다. Rust는 일반 주석과 문서 주석을 분리하여 지원하며, 사용 형식도 뚜렷하게 구분된다.
일반 주석에는 한 줄 주석과 여러 줄 주석이 있다. 한 줄 주석은 // 뒤에 주석 내용을 작성하며, //부터 해당 줄의 끝까지가 주석으로 인식된다. 여러 줄 주석은 /*와 */로 감싸진 구간 전체가 주석이 되며, 중첩해서 사용하는 것도 가능하다. 한 줄 주석은 코드 옆에서 간단한 메모나 디버깅을 위한 설명 등을 붙이기에 적합하고, 여러 줄 주석은 함수나 모듈의 큰 흐름, 알고리즘의 설계 아이디어 등을 길게 설명할 때 주로 사용된다.
코드 예시는 아래와 같다.
fn main() {
// 이 부분은 한 줄 주석이다.
println!("Hello, world!");
/*
이 부분은 여러 줄 주석이다.
여러 줄에 걸쳐 긴 설명을 작성할 때 사용한다.
*/
/* 중첩된 여러 줄 주석 가능 */
/*
외부 주석
/* 내부 주석 */
주석 종료
*/
}문서 주석은 코드나 API에 대한 문서화를 자동으로 생성하기 위해 사용된다. 이 기능은 Rust 도구 체인에 포함된 rustdoc 툴을 통해 작동하며, 문서 주석을 적절히 작성하면 cargo doc 등을 통해 HTML 문서를 간편하게 생성할 수 있다. 문서 주석은 크게 세 가지 형태로 구분된다. 첫 번째 형태는 ///로 시작하는 주석으로, 보통 함수나 구조체, 열거형 등의 앞에 위치해 그 대상에 대한 설명이나 사용 예시를 작성한다. 두 번째 형태는 //!로 시작하는 주석으로, 주로 크레이트나 모듈 단위로 전체적인 설명을 추가하는 데 사용된다. 세 번째 형태는 테스트를 동반한 문서화가 가능한 러스트만의 특징으로, 예시 코드를 문서 주석 안에 포함하면 cargo test 과정에서 해당 예시 코드가 실제로 컴파일 및 실행되어 유효성을 확인할 수 있다.
아래 코드는 문서 주석의 대표적인 예시이다.
위에서 /// 뒤에 작성된 내용은 함수 add에 대한 문서로 생성된다. 예시 코드를 포함하면 Rust의 문서화 도구가 이것을 테스트로 인식해, 문서에 예시가 그대로 보여지는 동시에 테스트로도 수행된다. 이때 예시 코드를 포함하는 부분에 Rust 코드 블록 표기(`````)를 사용하고, 함수의 실제 위치를 모듈 경로 등으로 명시하면 테스트가 원활하게 동작한다.
문서 주석은 함수나 타입 정의 바로 위에 위치해야 하며, 여러 라인에 걸쳐 사용할 때에는 매 라인마다 ///를 반복해서 적어주면 된다. 만약 모듈 전체에 대한 설명을 제공하고 싶다면, //! 문서 주석을 모듈의 가장 상단에 배치할 수 있다.
이와 같이 크레이트 레벨에서 사용하기 위해서는 #![...] 형태로 표기하고 내부에 doc = "..." 라는 형태로 설명을 넣는다. 모듈 레벨에서는 //!를 이용한다.
문서화와 문서 주석을 효과적으로 활용하면, 라이브러리를 사용하는 개발자 또는 프로젝트를 함께 진행하는 팀원들이 코드의 의도와 사용법을 한눈에 파악하기 쉬워진다. 또한 문서 주석 안에서 직접 예제 코드를 테스트할 수 있으므로, 문서와 실제 동작 간의 불일치를 막을 수 있다는 장점도 있다. 이러한 특징들은 Rust가 안전하고 유지보수하기 쉬운 코드를 추구하는 언어로서, 문서화 품질을 높이는 데 큰 도움을 준다.
Rust에서 주석은 코드 품질과 가독성을 높이는 필수적인 도구이다. 일반 주석과 문서 주석을 적절히 배치하고, 문서 주석 내 예시 코드를 통해 문서화와 테스트를 연계하면 보다 안전하고 명확한 Rust 코드를 작성할 수 있다.
Last updated