4.2 品質工具：fmt、clippy 與文件#

Rust 生態的品質三件套#

Rust 社群有一個少見的優勢：程式碼風格與品質檢查有官方統一的答案，不用像其他語言那樣吵 formatter 和 linter 的選擇：

cargo fmt：官方格式化工具（rustfmt），統一風格
cargo clippy：官方 linter，抓出低效、易錯的寫法
cargo doc：從註解產生 API 文件

cargo fmt：統一風格，零爭論#

cargo fmt            # 格式化整個專案
cargo fmt --check    # 只檢查有沒有不合格式的地方（CI 用）

風格由官方 rustfmt 決定，團隊不用吵縮排、括號位置
慣用法：commit 前跑一次 cargo fmt，或讓編輯器存檔時自動格式化
CI 中用 cargo fmt --check 擋掉未格式化的程式碼

cargo clippy：超過 700 條 lint 規則#

cargo clippy                      # 跑 linter
cargo clippy -- -D warnings       # 把警告當錯誤（CI 用）

Clippy 會抓出編譯器不會擋、但更差的寫法：

// clippy 提示：用 is_empty() 而不是 len() == 0
if v.len() == 0 { ... }        // ← warning
if v.is_empty() { ... }        // ✓

// clippy 提示：不必要的 return
return x + 1;                  // ← warning（最後一行不用 return）
x + 1                          // ✓

// clippy 提示：用 map 代替手寫循環（視情況）

工程實務：把 clippy 進 CI，並用 -D warnings 把警告擋在合併之前。Clippy 的建議幾乎都是對的，長期讓程式碼維持在慣用的、高效的寫法。

cargo doc：註解即文件#

Rust 的 API 文件（docs.rs）全部由 doc comment（///） 自動產生：

/// 計算矩形面積。
///
/// # 範例
///
/// ```
/// let r = Rectangle::new(3.0, 4.0);
/// assert_eq!(r.area(), 12.0);
/// ```
pub fn new(width: f64, height: f64) -> Self { ... }

cargo doc --open      # 產生文件並在瀏覽器打開

範例區塊（```）會被當成測試執行——文件裡的範例程式碼不會過時，因為跑不過就會讓測試失敗（見 6.2 節 doc test）。

把品質工具進 CI#

一個典型的 Rust CI 檢查組合（GitHub Actions 概念）：

cargo fmt --check          # 風格
cargo clippy -- -D warnings  # lint
cargo test                 # 測試
cargo build --release      # 建構

這四步是 Rust 專案的標準品質關卡——風格、慣用寫法、正確性、可建構，全部自動化。

本章小結#

品質三件套：cargo fmt、cargo clippy、cargo doc
風格官方統一，團隊零爭論；commit 前跑 cargo fmt
Clippy 進 CI、警告當錯誤：抓出低效與非慣用寫法
/// doc comment 產生文件，範例區塊會被當測試執行

想一想#

「官方統一 formatter」對團隊協作有什麼好處？其他語言為什麼做不到？
Clippy 抓的是編譯器不會擋的問題——舉一類它抓得到的錯誤。
「文件範例會被當測試執行」解決了什麼經典問題？