Revisão de Código e Qualidade

Visão Geral

Revisão de código multidimensional com portões de qualidade. Toda alteração é revisada antes de ser mesclada — sem exceções. A revisão abrange cinco eixos: correção, legibilidade, arquitetura, segurança e desempenho.

O padrão de aprovação: Aprove uma alteração quando ela definitivamente melhora a saúde geral do código, mesmo que não seja perfeita. Código perfeito não existe — o objetivo é a melhoria contínua. Não bloqueie uma alteração porque ela não está exatamente como você a escreveria. Se ela melhora a base de código e segue as convenções do projeto, aprove-a.

Quando Usar

• Antes de mesclar qualquer PR ou alteração
• Após concluir a implementação de um recurso
• Quando outro agente ou modelo produziu código que você precisa avaliar
• Ao refatorar código existente
• Após qualquer correção de bug (revise tanto a correção quanto o teste de regressão)

A Revisão de Cinco Eixos

Toda revisão avalia o código nessas dimensões:

1. Correção

O código faz o que afirma fazer?

• Ele corresponde à especificação ou aos requisitos da tarefa?
• Casos extremos são tratados (nulo, vazio, valores limite)?
• Caminhos de erro são tratados (não apenas o caminho feliz)?
• Ele passa em todos os testes? Os testes estão realmente testando as coisas certas?
• Existem erros de "off-by-one", condições de corrida ou inconsistências de estado?

2. Legibilidade e Simplicidade

Outro engenheiro (ou agente) consegue entender este código sem que o autor o explique?

• Os nomes são descritivos e consistentes com as convenções do projeto? (Sem temp, data, result sem contexto)
• O fluxo de controle é direto (evite ternários aninhados, callbacks profundos)?
• O código está organizado logicamente (código relacionado agrupado, limites claros de módulo)?
• Existem truques "inteligentes" que deveriam ser simplificados?
• Isso poderia ser feito em menos linhas? (1000 linhas onde 100 são suficientes é uma falha)
• Abstrações estão justificando sua complexidade? (Não generalize até o terceiro caso de uso)
• Comentários ajudariam a esclarecer intenções não óbvias? (Mas não comente código óbvio.)
• Existem artefatos de código morto: variáveis de "no-op" (_unused), "shims" de compatibilidade retroativa ou comentários // removed?
• Uma nova condição está sendo acoplada a um fluxo não relacionado? Isso é um "cheiro" de design, não um detalhe — mova a lógica para seu próprio helper, estado ou política em vez de emaranhar um caminho existente.
• Condicionais repetidos com a mesma forma aparecem? Eles sinalizam um modelo ou despachante ausente. Um branch "temporário" geralmente é dívida permanente.

3. Arquitetura

A alteração se encaixa no design do sistema?

• Ela segue padrões existentes ou introduz um novo? Se novo, é justificado?
• Ela mantém limites limpos de módulo?
• Existe duplicação de código que deveria ser compartilhada?
• As dependências fluem na direção certa (sem dependências circulares)?
• O nível de abstração é apropriado (não superengenharia, não muito acoplado)?
• Este refatoramento reduz a complexidade ou apenas a realoca? Conte os conceitos que um leitor precisa ter em mente para seguir a alteração. Se uma versão "mais limpa" não altera essa contagem, ela não é mais limpa — prefira a reestruturação que faz ramos, modos ou camadas inteiras desaparecerem em vez de uma que re-centraliza a mesma lógica. Prefira excluir uma abstração a polí-la.
• Lógica específica de recursos está vazando para um módulo compartilhado ou de propósito geral? Mantenha a lógica em sua camada proprietária, reutilize o helper canônico existente em vez de um quase duplicado e não normalize a deriva arquitetural.
• Os limites de tipo são explícitos? Questione any/unknown/opcionais/casts gratuitos e fallbacks silenciosos que mascaram um invariante pouco claro — tornar o limite explícito geralmente torna o fluxo de controle circundante mais simples.

4. Segurança

Para orientação detalhada de segurança, veja security-and-hardening. A alteração introduz vulnerabilidades?

• A entrada do usuário é validada e higienizada?
• Segredos são mantidos fora do código, logs e controle de versão?
• Autenticação/autorização são verificadas onde necessário?
• Consultas SQL são parametrizadas (sem concatenação de strings)?
• Saídas são codificadas para prevenir XSS?
• Dependências são de fontes confiáveis e sem vulnerabilidades conhecidas?
• Dados de fontes externas (APIs, logs, conteúdo do usuário, arquivos de configuração) são tratados como não confiáveis?
• Fluxos de dados externos são validados nos limites do sistema antes de serem usados na lógica ou renderização?

5. Desempenho

Para profiling e otimização detalhados, veja performance-optimization. A alteração introduz problemas de desempenho?

• Padrões de consulta N+1?

…