もう迷わない！Rustのコメントの書き方と実践的な使い方

Rustのコメントの書き方、どうしてますか？ Rustを学び始めたばかりだと、コードの書き方だけでなく、コメントの作法も気になるところですよね！

「他の言語と違うのかな？」「どんな種類があるの？」なんて疑問を持っているかもしれません。

実は、Rustのコメントはコードを分かりやすくするだけでなく、ドキュメントを自動で作ってくれる便利な機能もあるんです。

この記事では、Rustのコメントに関するアレコレを基本から実践的な使い方まで解説していきます！

この記事でわかること

• Rustの基本的なコメントの書き方がわかる
• コメントの種類と使い分けが理解できる
• 読みやすいコメントを書くためのコツが身につく
• ドキュメンテーションコメントの便利な使い方がわかる
• 自信を持ってRustのコードにコメントを付けられるようになる

さあ、一緒にRustのコメントの世界を探検してみましょう！

Rustのコメントとは？なぜ書く必要があるの？

プログラミングにおけるコメントは、コードの中に書くことができる、プログラムの動作には影響しないメモ書きのようなものです。じゃあ、なんでわざわざ書くの？って思いますよね。理由はいくつかあります。

コードが読みやすくなる

将来の自分へのメッセージ

チーム開発がスムーズに

一時的にコードを無効化できる（コメントアウト）

つまり、コメントは読みやすく、メンテナンスしやすいコードを作るための潤滑油みたいな役割を果たしてくれるんですね。面倒くさがらずに、適切なコメントを書く習慣をつけましょう！

【基本】Rustのコメントの書き方。2つの種類を覚えよう

Rustで使われるコメントには、大きく分けて2つの種類があります。まずはこの2つを押さえておけば大丈夫！

1. 通常コメント
   コードの中にメモを残すための、一般的なコメントです。
2. ドキュメンテーションコメント
   コードの説明書（ドキュメント）を自動生成するために使われる、ちょっと特別なコメントです。

それぞれの書き方と使い方を、順番に見ていきましょう。

通常コメント① 一行コメント (//) の書き方

一番よく使うのが、この一行コメントです。スラッシュを2つ (//) 書くと、そこから行末までがコメントとして扱われます。

書き方はとってもシンプル！

// これは一行コメントです。プログラムとしては無視されます。

fn main() {
    let x = 5; // ここにもコメントを書けます。変数xに5を代入。
    // println!("Hello, world!"); // この行はコメントアウトされているので実行されません。
    println!("xの値は: {}", x);
}

このように、行の先頭に書いたり、コードの後ろに続けて書いたりできます。短い注釈や、特定の行の説明をサッと書きたいときに便利です。コードの意図を簡潔に伝えるのがコツです。

通常コメント② 複数行コメント (/* */) の書き方

一行じゃ書ききれない、ちょっと長めの説明を書きたいときや、まとまったコードを一時的にコメントアウトしたいときは、複数行コメントを使います。

/* で始まり、*/ で終わるまでの範囲が、すべてコメントになります。

/*
これは複数行コメントです。
何行にわたって書いても大丈夫。
プログラムの動作には影響しません。
*/

fn main() {
    /*
    以下の部分は現在使っていないのでコメントアウト
    let y = 10;
    println!("yの値: {}", y);
    */
    println!("複数行コメントのテスト");

    let z = 15; /* 変数zの初期化 */ // ← こんな風に途中に書くこともできますが、あまり推奨されません
    println!("zの値: {}", z);
}

/* と */ の間なら、改行してもOK。複数行にわたる説明や、一時的なコードの無効化に使うのが主な用途です。

ただし、コメントの中にコメントを入れる（ネストする）こともできますが、コードが読みにくくなることがあるので注意しましょう。

【応用】Rustのドキュメンテーションコメントの書き方

ここからは、Rustのちょっとユニークで便利な機能、ドキュメンテーションコメントについて見ていきましょう！

これは単なるメモ書きではなく、コードから自動でキレイなドキュメント（説明書）を生成するための特別なコメントなんです。

自分で作った関数や構造体、ライブラリなどの使い方を説明するのに、ものすごく役立ちます。cargo doc というコマンドを実行すると、HTML形式のドキュメントが作られるんですよ。すごいですよね！

書き方には主に2種類あります。

アイテムの外側に書くドキュメンテーションコメント (///)

関数や構造体、モジュールなど、説明したい要素（アイテム）の「直前」に書くのが /// です。スラッシュ3つですね。

このコメントは、その直後にあるアイテムが「何をするものなのか」「どうやって使うのか」を説明するために使います。Markdown記法も使えるので、箇条書きやコード例なんかも書けちゃいます。

/// 2つの数値を足し合わせる関数
///
/// # Examples
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
fn add(a: i32, b: i32) -> i32 {
    a + b // ← これは通常のコメント
}

fn main() {
    let sum = add(10, 20);
    println!("合計: {}", sum);
}

上の例では、add 関数の上に /// で始まるコメントが書かれています。# Examples のように見出しを付けたり、バッククォート3つで囲んでコード例 (```) を示したりできます。公開するライブラリや、他の人が使う可能性のある関数には、積極的に書いておくと親切ですね！

アイテムの内側に書くドキュメンテーションコメント (//!)

もう一つは //! です。これは、そのコメントが書かれているファイルやモジュール全体など、「それを囲むアイテム自身」について説明するときに使います。

通常は、lib.rs や main.rs、あるいはモジュールを定義しているファイルの一番先頭に書くことが多いです。

//! このクレート（ライブラリ）は、数値計算に関する
//! 様々な便利な関数を提供します。
//!
//! `add` 関数や `subtract` 関数などが含まれています。

/// 2つの数値を足し合わせる関数
fn add(a: i32, b: i32) -> i32 {
    a + b
}

// ... 他の関数定義など ...

fn main() {
    println!("クレートのドキュメントテスト");
}

//! は、そのファイルやモジュールが全体として何なのかを示すのに使います。/// が個々の部品の説明だとしたら、//! はその部品が入っている箱全体の説明、みたいなイメージでしょうか。ライブラリのトップレベルの説明などに使うと良いでしょう。

【実践】Rustのコメントの使い方

さて、ここまで学んだコメントの種類を、実際のコードの中でどうやって使っていくのか、もう少し具体的な例で見てみましょう。

コメントがあると、コードがどれだけ分かりやすくなるか実感できるはずです！

サンプルプログラム紹介

ここでは、簡単な挨拶メッセージを生成する関数と、それを使うメイン関数を含むサンプルコードを用意しました。色々な種類のコメントを散りばめています。

//! あいさつメッセージを生成するサンプルプログラム
//!
//! このプログラムは、`create_greeting` 関数を使って、
//! 指定された名前に対する挨拶文を作成し、表示します。

/// 指定された名前を含む挨拶メッセージを作成します。
///
/// # Arguments
///
/// * `name` - 挨拶の対象となる名前（文字列スライス）
///
/// # Returns
///
/// * フォーマットされた挨拶メッセージ (`String`)
///
/// # Examples
///
/// ```
/// let message = create_greeting("Rustacean");
/// assert_eq!(message, "こんにちは、Rustaceanさん！");
/// ```
fn create_greeting(name: &str) -> String {
    // format! マクロを使って文字列を組み立てる
    let greeting = format!("こんにちは、{}さん！", name);
    /*
       将来的には、時間帯によって挨拶を変える機能も入れたい
       例: 午前中なら「おはようございます」
           夜なら「こんばんは」
       今は固定で「こんにちは」を返す
    */
    greeting // 組み立てた文字列を返す
}

fn main() {
    let user_name = "Alice"; // 挨拶する相手の名前
    let message = create_greeting(user_name); // 関数を呼び出してメッセージ作成

    println!("{}", message); // 作成したメッセージを表示
}

サンプルプログラムの解説

上のサンプルコードのコメントを、一つずつ見ていきましょう。

• //! あいさつメッセージを... (1行目から)
  これは //! で始まるドキュメンテーションコメントです。ファイル（クレート）全体の目的を説明しています。cargo doc を実行すると、このクレートのトップページの説明として表示されます。
• /// 指定された名前を含む... (9行目から)
  これは /// で始まるドキュメンテーションコメント。直後にある create_greeting 関数の説明です。引数 (Arguments)、戻り値 (Returns)、使い方 (Examples) が書かれていて、この関数が何をするものか、どう使えばいいかが一目で分かります。他の人がこの関数を使うときに、非常に頼りになる情報です。
• // format! マクロを使って... (24行目)
  これは一行コメントです。直後のコードが何をしているのか、短い補足説明を加えています。
• /* 将来的には... */ (25行目から)
  これは複数行コメントです。今は実装されていないけれど、将来的に追加したい機能についてのメモを残しています。複数行にわたるアイデアや、少し長めの注釈に便利です。
• // 組み立てた文字列を返す (31行目)
  これも一行コメント。関数の最後の処理（戻り値を返すこと）を明確にしています。
• // 挨拶する相手の名前 (35行目)
  一行コメントで、変数 user_name が何を表しているかを説明しています。
• // 関数を呼び出してメッセージ作成 (36行目)
  一行コメントで、create_greeting 関数を呼び出している処理内容を説明しています。
• // 作成したメッセージを表示 (38行目)
  一行コメントで、最後の println! が何をしているかを説明しています。

どうでしょうか？ コメントがあることで、コードの各部分が何をしているのか、どんな意図で書かれたのかが、ずっと追いやすくなったと思いませんか？

Rustのコメントを書く上での注意点と良いコメントのコツ

コメントは便利ですが、やみくもに書けばいいというものでもありません。いくつか注意点と、より良いコメントを書くためのコツを紹介します。

コードを見れば分かることは書かない