Linting & Formatting Best Practices

Low-friction, high-signal quality gates keep Rust codebases consistent without debate-driven review churn.

How to Use This List

• Adopt when bootstrapping CI or after fmt/clippy fire drills on main.
• Pair with Pre-commit & Editor Setup for local parity.
• Treat each allow as technical debt with an owner.

A - Formatting

• cargo fmt --all --check in CI. Zero manual style review.
• rustfmt.toml at workspace root with edition = "2024". Matches Cargo edition.
• Format on save via rust-analyzer. Same rules as CI.
• Unix newlines in rustfmt for cross-platform repos. Avoids snapshot/CI drift.
• No #[rustfmt::skip] without comment. Rare FFI/layout exceptions only.

B - Clippy

• cargo clippy --workspace --all-targets -- -D warnings on PRs. Tests and benches included.
• Optional --all-features matrix job. Cfg-gated code linted.
• clippy.toml documents disallowed APIs. e.g. ban raw std::env::var in apps.
• Per-crate [lints.clippy] for apps vs libs. Stricter unwrap_used deny in binaries.
• Review cargo clippy --fix diffs. No blind auto-fix merges.

C - Documentation Lints

• missing_docs = "warn" on published library crates. Ratchet to deny over time.
• RUSTDOCFLAGS="-D warnings" in doc CI job. Broken intra-doc links fail build.
• Doctests run in CI for public APIs. cargo test --doc --workspace.
• # Errors / # Safety sections on fallible and unsafe API. API guidelines compliance.
• Crate-level //! docs on every lib root. crates.io and docs.rs presentation.

D - Toolchain and CI

• rust-toolchain.toml pins 1.97.0 + rustfmt + clippy components. Local/CI parity.
• Lint job runs before or parallel to tests, not after. Fast failure on style.
• Swatinem/rust-cache or equivalent. Sub-5-minute lint jobs on warm cache.
• MSRV check job uses rust-version from manifest. Not only latest stable.
• pre-commit hooks mirror CI fmt/clippy subset. Optional but recommended.

E - Exceptions and Policy

• Line-level #[allow(clippy::...)] with reason comment. No file-level blanket allows.
• forbid(unsafe_code) on domain crates; single FFI crate exempt. Documented in ARCHITECTURE.
• Lint policy in CONTRIBUTING.md. New hires know expectations day one.
• Revisit allows on toolchain upgrade. New lints may replace custom allows.
• No debating style in PR comments. Point to rustfmt/clippy output instead.

FAQs

Related

• rustfmt - formatting
• Clippy - lint catalog
• Linting in CI - pipelines
• 50 Rust Rules - style rules

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.