O que é code review e como fazer revisões de código que ajudam

Code review é a etapa em que outra pessoa lê o seu código antes de ele entrar na branch principal, com o objetivo de achar problemas, compartilhar conhecimento e manter o projeto legível para quem vier depois. Em equipes que usam GitHub, GitLab ou Bitbucket, isso acontece dentro de um pull request (ou merge request): você abre a proposta de mudança, alguém revisa, comenta, aprova ou pede ajustes, e só então o código é integrado.

Parece burocracia, mas a revisão é um dos poucos momentos em que duas cabeças olham para a mesma linha com calma. É ali que se descobre que a função nova já existia em outro módulo, que o if não cobre o caso de lista vazia ou que o nome dados2 não diz nada para ninguém. Para o júnior, é também a forma mais rápida de aprender como o time pensa.

Este texto integra a série do glossário de programação, com uma proposta específica, que é abrir o mecanismo por dentro: o que acontece em cada etapa de uma revisão, o que o revisor realmente olha e como escrever comentários que ajudam em vez de travar o time.

Code review por dentro: o caminho de uma mudança até o merge

O fluxo varia entre empresas, mas o esqueleto costuma ser este:

1. Branch própria. Você sai da main para um ramo seu (git switch -c corrige-calculo-frete) e faz as alterações nela.
2. Pull request aberto. Você empurra a branch e abre o PR com título e descrição contando a alteração e o motivo dela.
3. Checagens automáticas. A integração contínua roda testes, linter e build. Se algo quebra aqui, nem vale a pena chamar um humano ainda.
4. Leitura do revisor. Uma ou mais pessoas leem o diff, deixam comentários em linhas específicas e escolhem entre comentar, aprovar ou pedir mudanças.
5. Rodadas de ajuste. Você responde, corrige, empurra novos commits. O revisor confere de novo.
6. Merge. Com aprovação e checagens verdes, o código entra na branch principal.

No GitHub, essas três saídas da revisão (comentário, aprovação e pedido de alteração) estão descritas na documentação de revisões de pull request do GitHub, e muitos repositórios configuram proteção de branch para exigir pelo menos uma aprovação antes do merge.

O que o revisor de código procura, em ordem de peso

Um erro comum de quem começa a revisar é gastar 90% da energia em espaços e vírgulas. O guia público de práticas de engenharia do Google, o Google Engineering Practices sobre code review, sugere uma ordem que funciona bem para qualquer time: primeiro o desenho geral, depois a funcionalidade, a complexidade, os testes, os nomes, os comentários e, por último, o estilo.

Repare que estilo está no fim. Formatação deveria ser resolvida por ferramenta (Prettier, Black, ESLint), não por comentário humano. Se o time discute ponto e vírgula em PR, falta configurar o linter, não sobra rigor.

Segurança e dados sensíveis também entram na leitura

Chave de API commitada, SQL montado com concatenação de string, log que imprime CPF: são coisas que passam fácil quando o autor está focado em fazer a feature funcionar. O revisor tem a vantagem de ler com distância. Tudo que toca autenticação, pagamento e dados pessoais merece um pouco mais de atenção.

O tamanho do pull request decide a qualidade da revisão

Esse é o detalhe que pouca gente conta para o júnior: um PR grande quase sempre recebe uma revisão pior. Com 40 linhas alteradas, o revisor lê cada uma. Com 1.500, ele rola a tela, confia no autor e aprova. As orientações de engenharia do Google também defendem alterações enxutas e focadas, justamente porque são revisadas mais rápido e com mais cuidado.

Na prática, quebre o trabalho. Se a tarefa é “criar tela de cadastro com validação e envio de e-mail”, dá para abrir três PRs: o modelo e a migração, a tela com validação, o envio de e-mail. Cada um faz sentido sozinho e pode ser lido em uma pausa de café.

Uma regra prática: se você precisa de mais de um parágrafo só para listar o que o PR mexe, ele provavelmente deveria ser dois.

Como escrever comentários de revisão que ajudam

O código é revisado, mas quem lê o comentário é uma pessoa. A diferença entre um time que gosta de revisão e um que teme revisão costuma estar no tom e na clareza dos comentários, não no rigor técnico.

Compare dois comentários sobre o mesmo trecho:

// Ruim
Isso tá errado.

// Útil
Se `itens` vier vazio, `itens[0].preco` vai lançar erro.
Que tal retornar 0 logo no início quando a lista estiver vazia?

O segundo aponta o problema, mostra o caso que quebra e sugere um caminho. O autor pode discordar, mas sabe exatamente do que se trata.

Algumas práticas que reduzem atrito:

• Marque a gravidade. Prefixos como “nit:” (detalhe, opcional), “dúvida:” ou “bloqueante:” evitam que o autor trate sugestão de nome como se fosse bug crítico.
• Pergunte antes de afirmar quando não tem certeza: “isso roda em toda requisição?” abre conversa; “isso é lento” fecha.
• Comente o código, não a pessoa. “Essa função ficou longa” em vez de “você escreveu uma função enorme”.
• Elogie o que ficou bom. Não por cortesia vazia: um “boa, esse teste cobre o caso que quebrou mês passado” ensina o que o time valoriza.
• Leve para conversa síncrona quando a troca passar de três rodadas no mesmo ponto. Dez minutos de chamada resolvem o que vinte comentários não resolvem.

Do lado de quem recebe o code review

Receber comentário no primeiro PR dói um pouco. Normal. Mas o revisor está comentando um diff, não sua capacidade.

Facilite a vida de quem vai revisar antes mesmo de pedir revisão. Releia o próprio diff na interface do GitHub como se fosse de outra pessoa; você vai achar console.log esquecido e arquivo que não deveria estar ali. Escreva na descrição do PR o que mudou, por que mudou e como testar. Se houver tela, anexe um print.

Quando discordar de um comentário, explique o motivo com argumento técnico. “Mantive assim porque essa função é chamada só no job noturno, então a performance não pesa” é uma resposta perfeitamente aceitável. E quando o revisor tiver razão, corrija e responda curto. Ninguém precisa de um pedido de desculpas por uma variável mal nomeada.

Quanto tempo esperar por uma revisão?

Times saudáveis tratam revisão como prioridade: o guia do Google recomenda responder em até um dia útil, no máximo. Se o seu PR está parado há dias, cobre com educação no canal do time. PR esquecido envelhece, gera conflito de merge e desanima quem escreveu.

Revisão feita por ferramentas e por IA: onde entra e onde para

Hoje boa parte da revisão superficial já é automatizada. Linters pegam estilo, análise estática acha variáveis não usadas e padrões inseguros, e assistentes de IA comentam PRs sugerindo melhorias. O buildbase já mostrou, por exemplo, como configurar o Code Review do Claude Code em um repositório.

Essas ferramentas são ótimas para tirar ruído da revisão humana. O que elas ainda não fazem bem é responder perguntas de contexto: essa regra de negócio está certa? Esse módulo deveria existir? O cliente pediu isso mesmo? Essa parte continua sendo trabalho de gente que conhece o produto.

Para começar a revisar código amanhã

Se você é júnior, não espere ser “sênior o suficiente” para revisar. Peça para ser adicionado como revisor em PRs do time, mesmo que sua aprovação não seja obrigatória. Leia, faça perguntas genuínas (“por que usar Map aqui em vez de objeto?”) e anote as respostas. Em poucas semanas você vai conhecer o código do projeto melhor do que lendo a documentação, e vai começar a escrever PRs que passam na primeira rodada.