O que é code review: como fazer e boas práticas

O que é code review

A Wikipédia define revisão de código como uma prática de engenharia de software em que uma ou mais pessoas, além do autor da mudança, examinam o código-fonte para avaliar sua qualidade antes ou durante a integração à base de código. O GitLab descreve o code review como uma avaliação feita por colegas que ajuda a garantir ou melhorar a qualidade do código antes do merge.

Na prática, o code review acontece dentro de um pull request (PR): quem escreveu abre o PR com a descrição da mudança, uma ou mais pessoas comentam linhas específicas, a autora ajusta o que for preciso e, com a aprovação, o código entra na branch principal.

Para que serve o code review

• Encontrar bugs cedo, enquanto quem escreveu ainda lembra do código e a correção é barata.
• Avaliar o design: se a mudança está no lugar certo e se o sistema continua fácil de manter.
• Manter a consistência de convenções, padrões e tratamento de erros em toda a base de código.
• Espalhar conhecimento, para que mais de uma pessoa entenda cada parte do sistema e ninguém vire gargalo.

As Engineering Practices do Google resumem o critério de um code review em uma regra: a mudança deve ser aprovada quando melhora claramente a saúde geral do código, mesmo que não esteja perfeita. Código perfeito não existe, só código melhor. Cada comentário pode ser medido por essa régua: ele deixa o código melhor ou só diferente?

Como fazer code review, passo a passo

A ordem abaixo segue o guia do Google para navegar por uma mudança, com os nomes da interface do GitHub em português:

1. Leia a descrição: Leia a descrição do pull request e a issue vinculada, e decida se a mudança faz sentido do jeito que foi proposta.
2. Revise primeiro o arquivo principal: Na aba Arquivos alterados, abra o arquivo com a lógica mais importante e avalie o design antes de entrar nos detalhes.
3. Leia os demais arquivos em ordem: Percorra os arquivos restantes na ordem em que aparecem, leia os testes junto e marque cada arquivo como Visualizado.
4. Comente com motivo e peso: Use Iniciar uma revisão, comente linhas específicas, explique o porquê de cada pedido e marque o que é opcional com Nit, Optional ou FYI.
5. Envie a revisão: Envie a revisão como Comentar, Aprovar ou Solicitar alterações e diga no resumo quais comentários bloqueiam o merge.

Dois detalhes do GitHub economizam tempo. Os comentários feitos com Iniciar uma revisão ficam pendentes até você clicar em Enviar revisão, e então chegam todos juntos. E se um arquivo mudar depois de marcado como Visualizado, o GitHub desmarca o arquivo, então na segunda rodada você vê de cara o que mudou.

Boas práticas de code review para quem escreve o código

1. Mantenha os PRs pequenos. O guia do Google considera 100 linhas alteradas um tamanho geralmente razoável e 1.000 geralmente grande demais. PRs pequenos são revisados mais rápido e com mais cuidado, introduzem menos bugs e são mais fáceis de reverter.
2. Explique a intenção, além do diff. Diga qual problema a mudança resolve, por que você escolheu essa abordagem e o que ficou de fora de propósito. Vincule a issue e aponte o arquivo com a lógica principal.
3. Separe refatoração de mudança de comportamento. Uma renomeação em 40 arquivos esconde as três linhas que mudam o comportamento. Mudanças mecânicas vão em um PR próprio.
4. Revise o próprio diff primeiro. Logs de debug, código comentado e testes faltando são mais fáceis de você tirar do que de alguém apontar.
5. Deixe a CI e a revisão automática rodarem antes de chamar alguém. Formatação, erros de lint e testes vermelhos não deveriam gastar a atenção de uma pessoa.
6. Responda a todos os comentários. Corrija ou explique por que discorda. Uma divergência resolvida na conversa vale mais do que um push silencioso que a pessoa revisora precisa comparar de novo.

Boas práticas de code review para quem revisa

7. Responda em até um dia útil. O guia do Google define um dia útil como o tempo máximo para responder a um pedido de revisão. Uma primeira resposta rápida vale mais do que uma revisão completa rápida.
8. Leia na ordem certa. Primeiro a descrição, depois o arquivo com a lógica principal. Um problema de design encontrado ali pode tornar o resto da revisão desnecessário, então avise logo.
9. Faça sessões curtas. A SmartBear relata, a partir de um estudo com uma equipe de programação da Cisco Systems, que revisar de 200 a 400 linhas em 60 a 90 minutos encontra de 70% a 90% dos defeitos, que a detecção cai bastante acima de 500 linhas por hora e que o desempenho diminui depois de uns 60 minutos.
10. Comente o código, não a pessoa. “Por que você usou threads aqui, se concorrência claramente não traz ganho nenhum?” soa como acusação. “O modelo de concorrência aqui adiciona complexidade sem um ganho de desempenho que eu consiga ver” descreve o código. Explique o porquê e sugira um caminho quando puder.
11. Marque o peso de cada comentário. Use Nit: para detalhes que podem ser ignorados, Optional: para ideias que valem considerar e FYI: para informação sem ação neste PR. Comentários sem marcação parecem obrigatórios.
12. Aprove com nits. O guia do Google recomenda aprovar mesmo com comentários em aberto quando eles são pequenos ou quando você confia que a autora vai resolvê-los. Isso poupa uma rodada inteira, principalmente entre fusos horários.

O papel de quem revisa é decidir se a mudança deixa o código mais saudável, e não fazer o código ficar igual ao que essa pessoa teria escrito. Comentários com motivo e nível de importância deixam a autora corrigir primeiro o que importa, e aprovar com nits abertos evita que uma boa mudança espere mais um dia por outra rodada.

Checklist de code review

• Design: a mudança está no lugar certo e combina com a arquitetura atual?
• Correção: o código faz o que a descrição promete? E com entrada vazia, valores-limite, erros e acesso concorrente?
• Testes: os testes novos cobrem o comportamento descrito? Algum teste existente foi afrouxado para passar?
• Segurança e dados: as entradas são validadas, as permissões checadas, e os logs ficam livres de segredos e dados pessoais, o que pesa ainda mais com a LGPD?
• Desempenho: há consultas dentro de laços, chamadas de rede desnecessárias ou listas que crescem sem limite?
• Legibilidade: os nomes são claros e os comentários explicam o porquê?

O que uma ferramenta consegue verificar vai para a CI em vez da checklist: formatter e linter resolvem indentação, ordem de imports e convenções de nome a cada execução. Regras que quem revisa repete nos comentários ficam melhor por escrito: convenções de código no AGENTS.md, orientações só de revisão no REVIEW.md, e requisitos caros de esquecer em uma verificação que roda em todo pull request correspondente.

Code review com IA

Com agentes de programação abrindo pull requests, o volume de código para revisar cresce, e esses PRs precisam da mesma revisão, muitas vezes de mais. No nosso benchmark de revisão de código escrito por agentes (em inglês), oito agentes implementaram as mesmas duas funcionalidades no Umami, um app de analytics de código aberto, e todos os 16 pull requests abertos tinham problemas.

Dos 119 problemas que o HeyDeer encontrou nesses 16 pull requests escritos por agentes, cada um conferido no código, 3 eram de severidade alta, 54 média e 62 baixa; nenhum foi classificado como crítico. A maioria causava danos limitados de funcionalidade, desempenho ou manutenção, o tipo de problema que se acumula sem ninguém notar.

Um revisor de IA rende mais quando passa primeiro. A configuração que o HeyDeer recomenda para equipes com revisores humanos: o HeyDeer revisa a cada push, a verificação falha enquanto houver achados em aberto, e as regras da branch exigem essa verificação. As pessoas começam a ler depois que ela passa e se concentram em design, comportamento do produto e nas perguntas que o HeyDeer lista em “Precisa de esclarecimento”.

• Formatação e lint: CI, a cada execução.
• Tratamento de erros, valores-limite, concorrência, chamadas quebradas: revisor de IA, a cada push.
• Regras do time caras de esquecer: verificações do repositório, em todo PR correspondente.
• Design, comportamento do produto, se a mudança deve existir: pessoas, depois que a revisão automática passa.

Em código escrito por agentes, revise também a tarefa: leia a issue ou o prompt usado e confira se a mudança faz isso e só isso. O modelo que escreveu o código tende a aceitar o próprio raciocínio e deixar passar os próprios erros; um revisor separado do autor encontra mais. Revise cada push, e não só o primeiro, porque revisões repetidas podem quebrar em silêncio o que uma versão anterior tinha acertado.

Se o revisor automático deixa comentários que ninguém usa, ajuste a configuração: mude o “Escopo do feedback” para “Conciso”, marque arquivos gerados e filtre PRs de bots. O guia como reduzir o ruído lista cada ajuste. O HeyDeer funciona no GitHub, tem um plano gratuito permanente, e os preços dos planos pagos estão publicados no site. Para ver como ele se compara a uma ferramenta conhecida, leia HeyDeer vs. CodeRabbit.

Fontes

1. Wikipédia: Revisão de código
2. GitLab: O que é uma revisão de código?
3. GitHub Docs: Revisar alterações propostas em um pull request
4. Google Engineering Practices: The standard of code review
5. Google Engineering Practices: Speed of code reviews
6. Google Engineering Practices: Small CLs
7. Google Engineering Practices: Navigating a CL in review
8. Google Engineering Practices: How to write code review comments
9. SmartBear: Best practices for peer code review