Convenções e Guia de Estilo

Idiomas Rust para toda a equipe reduzem o atrito nas revisões: formatação rustfmt, política clippy, nomenclatura, layout de módulos e divisão de tratamento de erros.

Receita

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings

# rustfmt.toml (raiz do repositório)
edition = "2024"
max_width = 100

Quando consultar este guia:

Ao escrever ou revisar qualquer PR
Ao integrar novos membros à equipe
Ao atualizar a política de lint da CI

Exemplo de Trabalho

Nomenclatura

// módulos e arquivos: snake_case
mod billing_tax;
 
// tipos: PascalCase
struct LineItem;
 
// funções: snake_case
fn calculate_tax() {}
 
// constantes: SCREAMING_SNAKE_CASE
const MAX_RETRIES: u32 = 3;

Erros

// crates/domain - biblioteca
#[derive(thiserror::Error, Debug)]
pub enum DomainError { /* ... */ }
 
// crates/api - binário
fn main() -> anyhow::Result<()> { Ok(()) }

Layout de Módulo

src/
  lib.rs or main.rs
  routes/        # Apenas HTTP no crate api
  error.rs
  state.rs

Mergulho Profundo

Política do Clippy

Nível	Regra
Negar	`unwrap_used` em `src/` de produção (permitido em testes)
Negar	Subconjunto `pedantic` selecionado pela equipe
Permitir	Documentado com `#[allow(clippy::...)]` + motivo

Mensagens de Commit

feat(api): adiciona sonda de prontidão [API-55]
fix(domain): rejeita item de linha com quantidade zero [BILL-12]

Assunto imperativo, ID do ticket, corpo explica o porquê.

Documentação da API

Itens públicos precisam de /// com exemplos que compilam em rustdoc:

/// Adiciona duas quantidades.
///
/// # Exemplo
/// ```
/// assert_eq!(add(1, 2), 3);
/// ```
pub fn add(a: u32, b: u32) -> u32 { a + b }

Armadilhas

Debates de formatação em PR - perda de tempo. Solução: rustfmt automático na CI.
allow clippy globalmente - esconde problemas reais. Solução: allow em nível de linha com comentário.
unwrap em libs - pânicos surpreendem os chamadores. Solução: Result ou expect com comentário de invariante apenas em testes.
Tipos de erro inconsistentes por módulo - fragmentação. Solução: um enum por crate.
pub(crate) ausente - API super-exposta. Solução: visibilidade mínima.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Pedantic mais rigoroso	Crítico para segurança	Velocidade inicial de desenvolvimento
Largura rustfmt personalizada	Genéricos longos	A menos que a equipe concorde

FAQs

Edição 2024 é obrigatória?

Quando edition = "2024" no Cargo.toml do workspace; corresponda ao manifesto, não a posts de blog.

Ordem de importação?

rustfmt lida com grupos; rust-analyzer organizar importações ao salvar é opcional.

Relacionados

Versões de 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+.

Exemplo de Trabalho

// módulos e arquivos: snake_case
mod billing_tax;
 
// tipos: PascalCase
struct LineItem;
 
// funções: snake_case
fn calculate_tax() {}
 
// constantes: SCREAMING_SNAKE_CASE
const MAX_RETRIES: u32 = 3;

// crates/domain - biblioteca
#[derive(thiserror::Error, Debug)]
pub enum DomainError { /* ... */ }
 
// crates/api - binário
fn main() -> anyhow::Result<()> { Ok(()) }

src/
  lib.rs or main.rs
  routes/        # Apenas HTTP no crate api
  error.rs
  state.rs

Mergulho Profundo

Nível	Regra
Negar	`unwrap_used` em `src/` de produção (permitido em testes)
Negar	Subconjunto `pedantic` selecionado pela equipe
Permitir	Documentado com `#[allow(clippy::...)]` + motivo

feat(api): adiciona sonda de prontidão [API-55]
fix(domain): rejeita item de linha com quantidade zero [BILL-12]

Assunto imperativo, ID do ticket, corpo explica o porquê.

Itens públicos precisam de /// com exemplos que compilam em rustdoc:

/// Adiciona duas quantidades.
///
/// # Exemplo
/// ```
/// assert_eq!(add(1, 2), 3);
/// ```
pub fn add(a: u32, b: u32) -> u32 { a + b }

Armadilhas

Debates de formatação em PR - perda de tempo. Solução: rustfmt automático na CI.

allow clippy globalmente - esconde problemas reais. Solução: allow em nível de linha com comentário.

unwrap em libs - pânicos surpreendem os chamadores. Solução: Result ou expect com comentário de invariante apenas em testes.

Tipos de erro inconsistentes por módulo - fragmentação. Solução: um enum por crate.

pub(crate) ausente - API super-exposta. Solução: visibilidade mínima.

Alternativa

Usar Quando

Não Usar Quando

Pedantic mais rigoroso

Crítico para segurança

Velocidade inicial de desenvolvimento

Largura rustfmt personalizada

Genéricos longos

A menos que a equipe concorde

Convenções e Guia de Estilo

Buscar na documentação

Convenções e Guia de Estilo