Introdução
Um código funcional é apenas uma parte de um projeto que outra pessoa possa manter com segurança. Uma crate Rust pronta para ser entregue também deve usar formatação consistente, evitar padrões suspeitos, explicar sua interface pública e manter os testes passando.
Neste laboratório, você reparará uma pequena biblioteca usando as ferramentas padrão de projetos Rust. Você introduzirá rustfmt, Clippy e rustdoc um de cada vez e, depois, os combinará com a suíte de testes em um ciclo de qualidade repetível. O código é intencionalmente pequeno para que você possa se concentrar no que cada ferramenta verifica.
Formate o código-fonte de maneira consistente
Nesta etapa, você usará rustfmt para detectar e corrigir diferenças de layout sem alterar o comportamento do programa.
Entre na biblioteca preparada e abra o código-fonte:
cd /home/labex/project/handoff-helpers
nano src/lib.rs
A primeira função é um código Rust válido, mas seus espaços e sua indentação diferem do restante do arquivo. As regras de formatação são mecânicas, portanto uma ferramenta pode aplicá-las com mais confiabilidade do que cada colaborador manualmente. Pressione Ctrl+X sem fazer alterações.
Primeiro, use o modo de verificação:
cargo fmt -- --check
É esperado que esse comando falhe e exiba um diff. cargo fmt seleciona os arquivos Rust do pacote. O primeiro -- encerra as opções do Cargo, e o segundo --check é passado ao rustfmt. O modo de verificação relata diferenças, mas não reescreve o arquivo, o que o torna útil em verificações automatizadas.
Agora aplique o formatador:
cargo fmt
Abra o código-fonte novamente:
nano src/lib.rs
A primeira função agora tem espaços, quebras de linha e indentação consistentes. Seus nomes e sua lógica não foram alterados. Saia do nano e confirme que o modo de verificação não produz saída:
cargo fmt -- --check
Nenhuma saída e uma finalização bem-sucedida significam que todos os arquivos Rust já seguem as regras do rustfmt.
Corrija os avisos do Clippy
Nesta etapa, você usará o Clippy para encontrar código que compila, mas pode expressar sua intenção com mais clareza.
O compilador Rust verifica se o código é válido e seguro em relação aos tipos. O Clippy adiciona lints para identificar padrões suspeitos, desnecessariamente complexos ou não idiomáticos. Execute-o promovendo os avisos a erros:
cargo clippy -- -D warnings
É esperado que essa primeira execução falhe. Assim como no rustfmt, -- passa a opção restante para a ferramenta subjacente. -D warnings significa negar avisos, portanto a verificação de qualidade termina com código diferente de zero até que todos os avisos relatados sejam corrigidos.
O Clippy identifica duas melhorias específicas: usar o método direto para verificar se algo está vazio, em vez de comparar um tamanho com zero, e aceitar uma fatia em vez de exigir que os chamadores sejam proprietários de um Vec. Abra o código-fonte:
nano src/lib.rs
Altere:
if cleaned.len() == 0 {
para:
if cleaned.is_empty() {
Depois, altere o parâmetro open_count de:
tasks: &Vec<bool>
para:
tasks: &[bool]
is_empty() expressa a pergunta diretamente. Uma fatia aceita dados de uma sequência emprestada sem exigir desnecessariamente o contêiner concreto Vec. Salve e saia do nano, formate a pequena alteração e execute o Clippy novamente:
cargo fmt
cargo clippy -- -D warnings
Uma linha final Finished, sem avisos, comprova que a biblioteca compila corretamente sob a política de lint mais rigorosa.
Documente a interface pública
Nesta etapa, você adicionará comentários de documentação e gerará uma documentação de API navegável.
Comentários iniciados com /// documentam o item imediatamente abaixo deles. Comentários iniciados com //! descrevem a crate ou o módulo que os contém. O Rustdoc transforma os dois formatos em documentação HTML com links.
Abra o código-fonte da biblioteca:
nano src/lib.rs
Adicione estas duas linhas no início do arquivo:
//! Small helpers for preparing task data for reports.
#![deny(missing_docs)]
O atributo interno transforma a ausência de documentação em itens públicos em um erro de compilação. Assim, a documentação deixa de ser apenas uma sugestão e passa a ser uma política explícita do projeto.
Adicione este comentário imediatamente acima de normalize_title:
/// Returns a trimmed title, or `Untitled` when the input is blank.
Adicione este comentário imediatamente acima de open_count:
/// Counts entries whose completion value is `false`.
Salve e saia do nano. Gere a documentação somente deste pacote:
cargo doc --no-deps
cargo doc executa o rustdoc. A opção --no-deps ignora a documentação das crates de dependência, mantendo o resultado mais focado e rápido. A página de entrada gerada é target/doc/handoff_helpers/index.html; o Cargo transforma o hífen do nome do pacote em sublinhado no nome da crate Rust.
ls target/doc/handoff_helpers/index.html
Ver esse caminho comprova que o rustdoc produziu a página da crate e que a política de documentação obrigatória foi satisfeita.
Execute o ciclo completo de qualidade
Nesta etapa, você combinará as ferramentas individuais em uma sequência previsível antes de entregar o projeto.
Formatação, linting, documentação e testes respondem a perguntas diferentes:
- o rustfmt verifica se o código-fonte tem o layout padrão;
- o Clippy verifica se ainda existem padrões conhecidos como suspeitos ou pouco claros;
- os testes verificam se o comportamento necessário continua funcionando;
- o rustdoc verifica se a interface pública pode ser documentada de acordo com a política do projeto.
Execute cada verificação separadamente para que uma falha aponte para um limite claro. Comece pela formatação:
cargo fmt -- --check
Execute o linting rigoroso:
cargo clippy -- -D warnings
Execute os testes da biblioteca:
cargo test
A saída deve informar que dois testes foram aprovados. Por fim, gere novamente a documentação focada:
cargo doc --no-deps
Quando os quatro comandos forem bem-sucedidos nessa ordem, a crate estará formatada de maneira consistente, sem problemas de lint, testada quanto ao comportamento e documentada. Executar o mesmo ciclo antes da entrega transforma a qualidade em evidência repetível, em vez de uma avaliação visual final.
Resumo
Você corrigiu a formatação com rustfmt, resolveu os avisos rigorosos do Clippy, documentou a interface pública de uma biblioteca, gerou a saída do rustdoc e manteve os testes passando. Mais importante, você combinou essas ferramentas em um ciclo de qualidade repetível que pode contribuir para uma entrega confiável do projeto.
