Rust Clippy and Fmt Tutorial

What and Why

Rust ships with two first-party code-quality tools: rustfmt and clippy. rustfmt normalizes whitespace, line breaks, and brace placement according to a community style. clippy is a linter that catches over 700 common mistakes, suboptimal patterns, and footguns - everything from if x == true to subtle borrow inefficiencies.

The “why” is consistency and learning. Format everything, and code-review discussions stop being about commas and indents. Run Clippy, and you’ll absorb idiomatic Rust faster than any tutorial can teach. Both tools are also installed via rustup, which means they ship at the same cadence as the compiler.

Mental Model

Think of rustfmt as a deterministic function from source code to canonical source code. It does not change meaning - only layout. You don’t need to argue with it; you configure it once in rustfmt.toml and forget.

Clippy is more nuanced. It runs as a Cargo subcommand and uses the compiler’s HIR (high-level intermediate representation) to analyze your code. Lints are grouped into categories: correctness (almost always bugs), suspicious, style, complexity, perf, pedantic, nursery, and cargo. The default profile includes the first five at warn level. Pedantic and nursery are opt-in - they’re noisier but excellent for learning.

Hands-on Example

Install both tools and run them.

rustup component add rustfmt clippy
cargo fmt
cargo clippy -- -D warnings

Given this code:

fn main() {
    let v = vec![1, 2, 3];
    let mut sum = 0;
    for i in 0..v.len() {
        sum = sum + v[i];
    }
    if sum == 6 { println!("ok"); }
}

Clippy will flag the index-based loop (needless_range_loop), the sum = sum + ... pattern (assign_op_pattern), and suggest if sum == 6 is fine but the body should be braced. After cleanup, the idiomatic version is:

fn main() {
    let v = vec![1, 2, 3];
    let sum: i32 = v.iter().sum();
    if sum == 6 {
        println!("ok");
    }
}

The diagram shows the loop: format first, lint second, test last, and gate commits with a hook.

Common Pitfalls

The most common pitfall is treating every Clippy warning as a bug. Many style and pedantic lints are opinions. If you disagree, add #[allow(clippy::lint_name)] locally with a comment explaining why, rather than silencing globally.

Another mistake is letting rustfmt versions drift across a team. CI should pin a Rust toolchain via rust-toolchain.toml so everyone formats identically. Otherwise, formatting churn pollutes diffs.

A subtle one: Clippy results depend on feature flags and target. A lint that fires on Linux may not fire on macOS if a cfg-gated module compiles differently. Run Clippy in CI for every target you support.

Finally, cargo clippy --fix is convenient but does not understand intent. Always review the diff before committing autofixed changes.

Practical Tips

Add cargo fmt --check and cargo clippy --all-targets --all-features -- -D warnings to your CI pipeline so PRs can’t merge with formatting drift or lint regressions. Use a rustfmt.toml with just a few opinionated overrides (like max_width or imports_granularity) instead of fighting defaults.

For larger codebases, opt into clippy::pedantic on a per-module basis using #![warn(clippy::pedantic)] at the top. This lets you adopt stricter rules incrementally. Pair Clippy with cargo machete to also catch unused dependencies, and cargo deny for license and advisory checks.

A pre-commit hook (via pre-commit or a custom script) that runs cargo fmt and cargo clippy --fix makes friction effectively zero for contributors.

Wrap-up

rustfmt and clippy are not optional extras - they are part of how Rust teams stay productive. Format ruthlessly, lint generously, and treat warnings as conversations with a senior reviewer. Once both tools are wired into your editor and CI, code quality becomes a passive byproduct of writing code at all.