Rust 註解

小提示

如果你曾學過 C、C++、Java 或 C#，可以跳過本單元。Rust 的註解用法和這些語言幾乎完全相同。

什麼是註解？

註解是給人閱讀的說明文字，編譯器會直接忽略，不會將其視為程式的一部分執行。

註解的用途

• 說明程式功能：協助他人更容易理解程式邏輯
• 記錄開發資訊：可用來產生技術文件
• 暫時停用程式碼：保留程式內容，但不讓它執行
• 提升程式碼可讀性

Rust 兩種主要註解類型

• 行內註解：以 // 開頭，作用範圍至該行結尾
• 區塊註解：使用 /* … */ 包覆程式區段，支援跨多行使用

註解就像你寫在課本上的筆記，用來幫助自己理解內容。

我們先介紹這兩種常用的註解形式，第三種類型會在後續章節說明。

fn main() {
    // 單行註解以兩個斜線開頭，範圍持續到該行結尾。
    // 同一行中，斜線後方的所有內容都會被編譯器忽略。

    // 範例：這行程式碼不會執行
    // println!("Hello, world!");

    // 試著刪除上方的斜線，再次執行程式。

    /*
     * 區塊註解可用來暫時停用程式碼。如下所示，
     * 它也支援巢狀寫法：/* 像這樣 */，適合快速將大段程式標註為註解。
     */

    /*
     * println!("Hello, world!");
     * println!("Hello, world2!");
     */

    /*
    備註：左側的星號僅為排版美觀使用，
    並非語法強制要求，可自行省略。
    */

    // 只要增減一個斜線，就能快速切換區塊內程式的啟用與停用狀態：

    /* <- 在這裡額外加一個斜線，就能解除下方整段區塊註解
       (將 /* 改為 //* 親自試試看)
    
    println!("現在");
    println!("所有");
    println!("程式都會執行！");
    // 內部的單行註解不會受到影響

    // */

    // 區塊註解也可以穿插在運算式中間：
    let x = 5 + /* 90 + */ 5;
    println!("`x` 的值是 10 還是 100？x = {}", x);
}Code language: PHP (php)

可以自行複製上方程式測試，尤其試試在 /* 前方多加一個斜線、啟用被區塊註解包覆程式的小技巧。

簡單來說，在 /* 前方加上斜線變成 //*，如此一來區塊註解的開頭就會失效，而後方的 // */ 也會被當成一般單行註解。

這就等同關閉了整段區塊註解，裡面的 println 程式便能正常執行。

文件註解

文件註解可透過專用工具轉換成 HTML 格式的線上文件，方便開發人員查閱。這部分我們會安排獨立章節來教學。