Melhores Práticas de Linting e Formatação

Portões de qualidade de baixo atrito e alto sinal mantêm bases de código Rust consistentes sem discussões de revisão que geram atrito.

Como Usar Esta Lista

• Adote ao iniciar a CI ou após "ataques de pânico" de fmt/clippy no main.
• Emparelhe com Configuração de Pré-commit e Editor para paridade local.
• Trate cada allow como débito técnico com um proprietário.

A - Formatação

• cargo fmt --all --check na CI. Zero revisão manual de estilo.
• rustfmt.toml na raiz do workspace com edition = "2024". Corresponde à edição do Cargo.
• Formatar ao salvar via rust-analyzer. Mesmas regras da CI.
• Quebras de linha Unix em rustfmt para repositórios multiplataforma. Evita desvios de snapshot/CI.
• Sem #[rustfmt::skip] sem comentário. Apenas exceções raras de FFI/layout.

B - Clippy

• cargo clippy --workspace --all-targets -- -D warnings em PRs. Testes e benchmarks incluídos.
• Job de matriz opcional --all-features. Código com cfg-gated é lintado.
• clippy.toml documenta APIs proibidas. Ex: proíbe std::env::var bruto em aplicativos.
• [lints.clippy] por crate para aplicativos vs. bibliotecas. Negação mais rigorosa de unwrap_used em binários.
• Revise os diffs de cargo clippy --fix. Sem mesclagens cegas de auto-correção.

C - Lints de Documentação

• missing_docs = "warn" em crates de biblioteca publicados. Ratchet para negar ao longo do tempo.
• RUSTDOCFLAGS="-D warnings" no job de CI de doc. Links intra-doc quebrados falham na compilação.
• Doctests executados na CI para APIs públicas. cargo test --doc --workspace.
• Seções # Errors / # Safety em APIs falíveis e inseguras. Conformidade com as diretrizes da API.
• Docs //! em nível de crate na raiz de cada biblioteca. Apresentação em crates.io e docs.rs.

D - Toolchain e CI

• rust-toolchain.toml fixa componentes 1.97.0 + rustfmt + clippy. Paridade local/CI.
• Job de lint executa antes ou em paralelo aos testes, não depois. Falha rápida em estilo.
• Swatinem/rust-cache ou equivalente. Jobs de lint de menos de 5 minutos com cache aquecido.
• Job de verificação MSRV usa rust-version do manifesto. Não apenas o último estável.
• Hooks de pre-commit espelham o subconjunto fmt/clippy da CI. Opcional, mas recomendado.

E - Exceções e Política

• #[allow(clippy::...)] em nível de linha com comentário de motivo. Sem allows genéricos em nível de arquivo.
• forbid(unsafe_code) em crates de domínio; única crate FFI isenta. Documentado em ARCHITECTURE.
• Política de lint em CONTRIBUTING.md. Novos contratados conhecem as expectativas no primeiro dia.
• Revisar allows na atualização da toolchain. Novos lints podem substituir allows personalizados.
• Não debater estilo em comentários de PR. Aponte para a saída de rustfmt/clippy em vez disso.

FAQs

Relacionados

• rustfmt - formatação
• Clippy - catálogo de lints
• Linting em CI - pipelines
• 50 Regras Rust - regras de estilo

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.