Code review na prática

Como dar e receber code review de forma útil: o que comentar, como receber críticas de código, e os erros que tornam o review uma perda de tempo para todo mundo.

Code review é uma das práticas que mais divide desenvolvedores. Alguns adoram a chance de aprender com outros; outros temem receber crítica. Quem dá o review não sabe o que comentar: ou fica em silêncio, ou comenta coisas demais que não agregam. Quem recebe sente como ataque pessoal. O resultado final: PRs que ficam semanas esperando aprovação, comentários que não trazem valor, ou rubber-stamp, que é quando alguém aprova sem revisar de verdade.

Este guia foca em tornar o review útil: não perfeito, não excessivo, apenas efetivo. O objetivo é que você saiba o que comentar, como receber crítica e como estruturar seu código (e sua PR) para que o review seja rápido e produtivo.

O que o code review não é

Antes de falar no que revisar, vamos limpar a visão do que review não é:

Não é sobre estilo: se você está comentando espaços, ponto-e-vírgula e order de imports, automatize isso com linter e formatter. Deixe a máquina decidir, não gaste review neles.
Não é prova de que o revisor é mais inteligente: review é feedback sobre essa mudança específica, não uma competição ou exame de conhecimento.
Não é aprovação de todo o código que você já escreveu: você não está selando o histórico da pessoa, apenas essa PR.
Não é opcional quando existe: ignorar comentários legítimos de review é o que destrói confiança dentro de times. Se você abre o PR com review, respeite o processo.

O que revisar de verdade

A arte da review está em focar no que importa. Aqui estão as dimensões de review em ordem de prioridade:

Corretude: o código faz o que diz que faz? Há casos de borda não tratados? (O que acontece com lista vazia, null, valores negativos?)
Segurança: há inputs do usuário não validados? Queries concatenadas? Secrets expostos? Se esse for um padrão do projeto, link para a política de segurança.
Legibilidade: um dev que não escreveu isso consegue entender em 5 minutos? Nomes de variáveis e funções comunicam a intenção?
Testes: a mudança tem testes? Os testes testam o comportamento importante, ou só o caminho feliz?
Performance: há algo obviamente ineficiente (N+1 queries, loop dentro de loop em dados grandes)?
Consistência: o código segue os padrões existentes do codebase?

Nitpicks (nomes opcionados, formatação) devem ser marcados explicitamente como "nit:" ou "opcional:" para não bloquear o merge.

Como escrever comentários úteis

O comentário que você escreve é uma ferramenta. Ela pode constatar um problema ou abrir caminho para melhorar. Aqui estão os princípios:

Seja específico e explique o porquê: "Isso pode causar N+1 queries quando users tem muitos itens. Considere eager loading aqui" é muito melhor que "performance issue".
Separe bloqueante de sugestão: use prefixos explícitos - "bloqueante:", "sugestão:", "nit:", "pergunta:" deixam claro o que precisa ser feito.
Pergunte antes de assumir: "Por que você escolheu X? Estava pensando em Y, mas talvez haja algo que estou perdendo". Isso abre o diálogo.
Ofereça alternativa: um comentário com sugestão é muito mais acionável que apontar só o problema.
Elogie quando merece: "Essa abstração ficou limpa" mostra que você leu o código com atenção genuína.

Evite comentários vagos ("isso não está certo"), tom condescendente ("óbvio") e nitpicks sem marcação que bloqueiam PRs por dias.

Como receber code review

O comentário é sobre o código, não sobre você. Leia assim. Aqui está como virar essa crítica em aprendizado:

Leia o comentário com mente aberta: o revisor não está dizendo que você é ruim, que você fez errado, que você é burro. Ele está lendo seu código e achou algo.
"Não concordo" é válido - mas exige argumento: "Concordo que parece estranho, mas nesse caso específico X porque Y" é uma resposta profissional.
Pergunte quando não entender: "Você pode elaborar?" é melhor que ignorar ou aceitar cegamente.
Responda todos os comentários: mesmo que seja só "feito" ou "vou deixar como está porque X". Deixar sem resposta desrespeita o tempo do revisor.
Agradeça feedback real: "Boa visão, não tinha pensado nisso" incentiva o revisor a continuar sendo cuidadoso.

Tornando o review mais eficiente

Review lento é um sintoma de problemas estruturais, não de falta de vontade. Aqui estão as mudanças que você pode fazer:

PRs menores são revisadas melhor: PR de 50 linhas recebe review detalhado. PR de 800 linhas recebe rubber-stamp. Regra prática: menos de 400 linhas por PR.

Descreva seu PR: o que muda, por que muda, como testar. O revisor não tem o contexto que você tem na cabeça.

Auto-review primeiro: olhe seu próprio diff antes de pedir review. Você vai encontrar metade dos problemas sozinho.

Pair para contexto complexo: se uma mudança é grande ou complexa, pair com alguém antes de abrir o PR. O review fica muito mais rápido depois.

Use essa checklist para você mesmo:

- [ ] Você marca comentários de nitpick explicitamente para não bloquear PRs por estilo?
- [ ] Quando você dá um comentário bloqueante, explica o porquê?
- [ ] Seus PRs têm descrição do que muda e como testar?
- [ ] Você responde todos os comentários (mesmo os que discorda)?