Artigo técnico · Rust · Engenharia de software · Revisão de código
Introdução
O Rust Style Guide do Google é um conjunto de diretrizes para escrever código Rust legível, consistente, sustentável e adequado a projetos de grande porte. Não se limita à formatação: aborda organização de módulos, desenho de APIs, ownership, empréstimos (borrowing), concorrência, macros, documentação, testes e tratamento de erros. [[1]](https://google.github.io/styleguide/rustguide.html)
A principal característica do documento é tratar o estilo como uma questão de engenharia de software, e não apenas de preferência estética. O objetivo é reduzir ambiguidades nas revisões, facilitar a manutenção e permitir alterações automatizadas em grandes bases de código.
Minha avaliação é que o guia oferece recomendações valiosas para projetos profissionais, mas precisa ser interpretado de acordo com o contexto. Algumas regras refletem boas práticas amplamente aplicáveis ao ecossistema Rust; outras respondem às necessidades particulares de infraestrutura, ferramentas de compilação e processos internos do Google.
Princípios e recomendações centrais
Legibilidade e manutenção acima da conveniência imediata
O Google privilegia código fácil de compreender e modificar, mesmo quando isso exige um pouco mais de trabalho durante a implementação. A ideia é que o custo adicional de escrever código explícito pode ser compensado por menos erros, revisões mais rápidas e menor esforço de manutenção.
Essa orientação é especialmente importante em sistemas mantidos por equipes ao longo de muitos anos. Entretanto, legibilidade não significa necessariamente escrever mais código: uma abstração bem escolhida pode ser mais clara do que uma sequência extensa de instruções.
Organização modular e dependências explícitas
O guia recomenda módulos com responsabilidades identificáveis, crates pequenos quando isso fizer sentido e imports explícitos, evitando o uso indiscriminado de use ...::*.
A intenção é facilitar a localização das definições e identificar a origem dos símbolos. Isso também ajuda ferramentas de busca e refatoração a operar de maneira previsível.
A ressalva é que modularização excessiva pode fragmentar o projeto e criar dependências artificiais. A divisão deve acompanhar as fronteiras conceituais do sistema, não simplesmente produzir o maior número possível de crates.
Ownership e borrowing como fundamentos do projeto
O documento incentiva o uso de referências e empréstimos em vez de cópias profundas desnecessárias, além de recomendar evitar Rc e Arc quando ownership e borrowing convencionais forem suficientes. [[1]](https://google.github.io/styleguide/rustguide.html)
Essas recomendações exploram uma das principais vantagens de Rust: representar a propriedade e o compartilhamento de dados de maneira explícita, permitindo que o compilador verifique muitas classes de erros de memória.
É importante, porém, não transformar essas diretrizes em dogmas. Arc, Rc e clone() são ferramentas legítimas quando simplificam o modelo de propriedade ou atendem aos requisitos de concorrência e desempenho. O próprio guia admite exceções quando a alternativa seria excessivamente complexa.
APIs genéricas, expressivas e seguras
O Google favorece interfaces que expressem a intenção do programador e reduzam restrições desnecessárias aos consumidores da API.
| Recomendação | Exemplo | Benefício esperado |
|---|---|---|
| Receber referências flexíveis | &str em vez de &String | Aceita mais formas de dados sem exigir propriedade |
| Preferir tipos semanticamente distintos | Newtypes em vez de aliases simples | Reduz confusões entre valores representados pelo mesmo tipo primitivo |
| Usar campos nomeados | struct Point { x: i32, y: i32 } | Torna os dados mais claros do que tuplas posicionais |
| Preferir enum a bool em APIs com alternativas | Mode::Read ou Mode::Write | Torna a intenção da chamada explícita |
| Usar correspondência de padrões | match | Expõe os casos tratados e os caminhos de erro |
Essas práticas são particularmente úteis em bibliotecas públicas, nas quais decisões de interface podem afetar muitos projetos. Para aplicações internas, o próprio Google recomenda evitar generalização prematura e priorizar simplicidade e objetividade. [[1]](https://google.github.io/styleguide/rustguide.html)
Tratamento de erros e código defensivo
O guia favorece mensagens de erro que forneçam contexto, recomenda expect() em situações nas quais uma condição invariável deve ser explicitada e desestimula o uso indiscriminado de unwrap().
Também orienta a preferir match a verificar uma condição e depois chamar unwrap(), evitando separar a verificação da operação que depende dela.
O mérito dessa abordagem é tornar as premissas do programa visíveis. Contudo, trocar mecanicamente todo unwrap() por expect() não resolve o problema fundamental: é necessário decidir se a situação representa um erro recuperável, uma falha de programação ou uma condição realmente impossível.
Automação, macros e concorrência
O documento favorece ferramentas automáticas de formatação, desencoraja macros quando funções e tipos comuns forem suficientes e exige justificativas técnicas para código unsafe. Também contém regras específicas de determinadas bases, como Chromium e Fuchsia. [[1]](https://google.github.io/styleguide/rustguide.html)
Essas orientações precisam ser distinguidas das recomendações gerais da linguagem. Por exemplo, a proibição de async/.await e a preferência por sequências em vez de novas threads aparecem identificadas como regras específicas do Chromium, não como proibições universais de Rust.
Essa distinção é essencial: copiar as regras sem suas condições de aplicação pode levar a decisões inadequadas em aplicações de rede, servidores assíncronos ou sistemas que utilizem outro modelo de execução.
A opinião da comunidade Rust e as principais críticas
A publicação do guia também provocou discussão entre desenvolvedores. Uma discussão no Reddit, em r/learnrust, publicada em 21 de outubro de 2026, recebeu centenas de votos e destacou justamente as recomendações que mais se afastam das convenções usuais do ecossistema. Os comentários são úteis para identificar pontos de debate, mas não constituem uma pesquisa representativa de toda a comunidade Rust. [4]
O que tende a ser bem recebido
Há uma convergência importante entre o guia do Google e os princípios gerais do Rust: legibilidade, APIs coerentes, documentação útil, segurança de memória e uso criterioso de abstrações.
A própria documentação oficial de estilo do Rust estabelece a legibilidade como prioridade, incluindo a facilidade de leitura em diffs, mensagens do compilador e ambientes sem realce de sintaxe. Isso mostra que a preocupação do Google com a manutenção não é exclusiva de sua cultura de engenharia. [[2]](https://doc.rust-lang.org/style-guide/)
A comunidade também tem bons motivos para valorizar a redução de debates subjetivos em revisões de código. Quando uma equipe concorda antecipadamente sobre formatação, nomenclatura e estrutura de APIs, pode concentrar as revisões na correção, segurança e arquitetura do programa.
Onde surgem as divergências
Organização plana e crates pequenos
A recomendação de evitar subdiretórios para arquivos de um mesmo crate no Chromium é uma das mais discutíveis. Em projetos menores, pode simplificar a navegação e o sistema de build. Em sistemas grandes, entretanto, diretórios hierárquicos podem representar naturalmente subsistemas e domínios funcionais.
Crítica: dividir um crate sempre que sua estrutura interna exigir subdiretórios pode transformar uma decisão organizacional em fragmentação artificial. O critério deveria ser a coesão, o acoplamento e a fronteira de compilação, não apenas o formato da árvore de arquivos. [[1]](https://google.github.io/styleguide/rustguide.html)
Restrições a Rc e Arc
Evitar compartilhamento de propriedade desnecessário é uma boa orientação. Entretanto, esses tipos resolvem problemas reais: grafos de objetos compartilhados, caches, estado compartilhado e estruturas concorrentes.
Crítica: a escolha entre ownership exclusivo, referências e compartilhamento deve decorrer do modelo de dados. Uma preferência inicial por empréstimos é sensata; uma regra cultural que desencoraje o compartilhamento mesmo quando ele expressa melhor o domínio não é.
Proibição de async/.await no Chromium
Essa regra é explicitamente específica do Chromium. Não deve ser interpretada como recomendação geral para aplicações Rust.
Crítica: ecossistemas assíncronos são amplamente utilizados em servidores, redes e sistemas de entrada e saída. Uma restrição pode fazer sentido quando o projeto já possui um modelo próprio de execução e agendamento, mas não se transfere automaticamente para outros sistemas. [[1]](https://google.github.io/styleguide/rustguide.html)
Preferência por funções e tipos em vez de macros
O guia chama atenção para os custos de macros: maior dificuldade de navegação, depuração e refatoração. Essa preocupação é legítima.
Crítica: macros declarativas e procedurais também permitem implementar abstrações que seriam impraticáveis ou excessivamente repetitivas com funções convencionais. Evitá-las por padrão é razoável; tratá-las como sinal de má engenharia não seria.
Ênfase em expect(), unwrap() e falhas
O guia procura tornar as premissas explícitas e reduzir pânicos evitáveis. Isso favorece diagnósticos mais úteis.
Crítica: expect() não é intrinsecamente mais seguro do que unwrap(). A segurança depende da política de tratamento de erros, da validade das invariantes e da possibilidade de recuperação. Trocar uma chamada pela outra sem revisar a lógica produz sobretudo uma mudança de mensagem.
Uma observação importante: essas críticas são análises técnicas das regras e de seus possíveis efeitos, e não alegações de que todos os desenvolvedores Rust rejeitam o guia. O debate comunitário identificado destaca algumas dessas divergências, mas não permite quantificar o apoio ou a rejeição a cada recomendação.
Avaliação técnica consolidada
| Critério | Avaliação |
|---|---|
| Legibilidade e manutenção | Muito bem fundamentado |
| Segurança e ownership | Bem fundamentado, com necessidade de julgamento contextual |
| Desenho de APIs públicas | Muito útil para bibliotecas |
| Automação e revisão de código | Especialmente adequado a grandes equipes |
| Organização modular | Dependente da arquitetura e do sistema de build |
| Concorrência e execução assíncrona | Regras específicas não devem ser generalizadas |
| Aplicação em projetos pequenos | Exige simplificação e adaptação |
O aspecto mais importante é que o documento reúne recomendações de naturezas diferentes: princípios gerais de engenharia, escolhas de design de APIs, convenções de equipe e restrições operacionais de projetos específicos. Aplicar tudo como um conjunto uniforme de regras obrigatórias seria um erro metodológico.
Conclusão
O guia de estilo Rust do Google é uma referência útil para quem deseja elevar a qualidade de uma base de código, especialmente em equipes grandes, bibliotecas compartilhadas e projetos com ciclos longos de manutenção. Seu mérito está em transformar decisões recorrentes de engenharia em convenções explícitas, facilitar a automação e reduzir divergências improdutivas durante as revisões.
As críticas mais relevantes dizem respeito à possibilidade de transformar preferências contextuais em regras universais. A organização plana pode não ser apropriada para todo domínio; o compartilhamento de propriedade pode ser necessário; macros podem oferecer abstrações superiores; e restrições à programação assíncrona dependem da arquitetura do sistema.
Minha recomendação é adotar o guia como referência, não como dogma. Para um projeto Rust independente, eu começaria pelo rustfmt, pelas convenções oficiais da linguagem, pelas recomendações de API e pelos princípios de ownership e tratamento de erros. Em seguida, incorporaria as regras específicas do Google somente quando houvesse uma justificativa concreta relacionada à arquitetura, à manutenção ou às ferramentas utilizadas.
Em última análise, o melhor estilo não é aquele que reproduz integralmente a cultura de uma empresa, por maior que ela seja. É aquele que torna o código mais fácil de entender, testar, modificar e operar sem introduzir complexidade desnecessária.
Referências
- Google. Rust Style Guide. https://google.github.io/styleguide/rustguide.html.
- Rust Project. The Rust Style Guide. https://doc.rust-lang.org/style-guide/.
- Rust Project. Rust API Guidelines. https://rust-lang.github.io/api-guidelines/.
- Comunidade r/learnrust. Discussão sobre o guia de estilo do Google (outubro de 2026).