Code review: como apontar o problema sem parecer babaca

O comentário tecnicamente correto que estraga o dia

Você abre o pull request e lá está:

"Isso tá errado."

Três palavras. Tecnicamente, pode até estar certíssimo. Mas o efeito na pessoa do outro lado é o mesmo de levar um empurrão no corredor.

E aí o PR trava. A pessoa responde defendendo a escolha. Você responde explicando melhor. Ela responde meio seca. Dois dias depois o código sai igual ao que ia sair, só que agora tem um clima estranho na daily.

Já viveu isso? De um lado ou do outro? Eu já vivi dos dois — e o lado de quem escreve o comentário ruim é mais fácil de estar do que a gente imagina.

O problema é o meio, não a maldade

Quase ninguém escreve comentário de review querendo ferir. O problema é estrutural.

Code review é texto, assíncrono e público. Não tem tom de voz, não tem cara, não tem o "risinho" que na mesa amaciaria a frase. E o time inteiro lê.

Quando falta tom, quem lê preenche sozinho. E a pessoa que acabou de passar seis horas naquele código, insegura sobre o resultado, vai preencher pro lado ruim. Sempre.

O mesmo comentário dito de pé, ao lado da mesa, com uma pausa e um "cara, olha só", passa liso. Escrito, vira julgamento.

Então não é sobre ser bonzinho. É sobre compensar o que o meio tira.

Sete coisas que mudaram meus reviews

1. Comente o código, não a pessoa

Trocar "você" por "esse método" muda tudo, e não custa nada:

❌ "Você esqueceu de tratar o retorno nulo aqui."
✅ "Esse retorno pode vir nulo quando o cliente não tem endereço — dá exception na linha de baixo."

Mesma informação. Só que a segunda fala do código, e a primeira aponta o dedo.

2. Diga o porquê e o impacto

Comentário sem motivo vira gosto pessoal — e ninguém aceita gosto pessoal de bom grado.

❌ "Não usa all() aqui."
✅ "Esse all() carrega a tabela inteira na memória. Em produção são uns 800 mil registros, o job vai estourar o limite. chunkById() resolve."

A segunda versão não precisa de autoridade nenhuma pra convencer. O argumento se defende sozinho, e a pessoa aprende algo em vez de só obedecer.

3. Separe o que bloqueia do que é preferência

Essa é a que mais melhora review em time, e é a mais fácil de adotar. Prefixo no comentário:

• bloqueante: — não pode subir assim (bug, falha de segurança, quebra de contrato)
• sugestão: — melhoraria, mas é decisão sua
• nit: — implicância mínima, pode ignorar sem culpa
• dúvida: — eu não entendi, me explica

Sem isso, todo comentário pesa igual. Quem recebe dez apontamentos não sabe se tem um problema sério ou dez preferências, e trata tudo como reprovação.

Com prefixo, "nit: acho que esse nome ficaria melhor no plural" é lido em dois segundos e resolvido em cinco.

4. Pergunta de verdade, não pergunta retórica

Existe uma diferença enorme entre curiosidade e ironia disfarçada de pergunta:

❌ "Tem certeza que isso funciona?"
❌ "Por que você fez desse jeito?"
✅ "Fiquei em dúvida no caso do cliente sem contrato ativo — esse where cobre isso? Posso ter perdido alguma coisa."

As duas primeiras são acusação com ponto de interrogação no fim. Todo mundo sente.

E tem um bônus real na terceira: às vezes quem não entendeu foi você. Manter a abertura de "posso ter perdido alguma coisa" já me salvou de várias sugestões erradas ditas com confiança demais.

5. Sugira o código, não só o problema

O GitHub e o GitLab têm bloco de sugestão. Usa. Escrever a alternativa custa trinta segundos e muda a natureza do comentário: em vez de tarefa, vira ajuda.

E força você a conferir se a sua ideia realmente funciona ali. Já desisti de uns bons comentários no meio da escrita da sugestão. 😅

6. Comente o que tá bom também

Não é bajulação nem "elogio sanduíche". É calibragem.

Se você só aparece pra apontar problema, seus comentários viram sinal de perigo — a pessoa vê seu nome na notificação e já se contrai. Um "esse teste do cenário de borda ficou ótimo, eu não tinha pensado nesse caso" custa dez segundos e muda como todo o resto é lido.

E tem um efeito colateral bom: elogiar o que você quer ver mais espalha padrão muito mais rápido do que criticar o que você não quer.

7. Passou de três idas e voltas, sai do texto

Se o mesmo ponto já teve três rodadas de comentário, o problema não é mais técnico. Ou vocês estão discutindo coisas diferentes, ou tem contexto que não cabe em caixa de texto.

Cinco minutos de call resolvem o que dez comentários não resolvem — e depois alguém registra no PR o que ficou combinado.

A pegadinha: review de gosto pessoal

Metade dos comentários azedos do mundo são sobre coisa que máquina deveria resolver.

Aspas simples ou duplas, quebra de linha, ordem dos imports, espaço antes da chave. Se isso aparece em review, o problema não é a pessoa — é que falta Pint (ou Pint + PHPStan) no pipeline.

Configura uma vez, o robô aponta, ninguém se ofende com robô. E aí o review humano fica livre pro que importa: regra de negócio, caso de borda, nome que não descreve o que faz, teste que não testa nada.

Regra que eu tento seguir: se um linter poderia ter dito, um humano não deveria dizer.

Do outro lado: recebendo review

Vale dizer, porque é mão dupla.

Todo comentário é sobre o código. Mesmo o mal escrito — quem escreveu provavelmente estava com pressa entre duas reuniões, não com raiva de você. Se um comentário te irritou, espera vinte minutos antes de responder. E se foi grosseiro mesmo, dá pra falar direto: "esse comentário soou meio seco, o que você quis dizer?". Quase sempre a resposta é "ih, desculpa, escrevi correndo".

E quando discordar, discorda com argumento. Review não é ordem, é conversa — quem revisa também erra.

Bônus: combinem uma página de regras

Meia hora de conversa e um documento de uma página resolvem 80% do atrito: o que é bloqueante de verdade, em quanto tempo se espera resposta num PR, tamanho máximo de PR (o maior favor que você faz pro revisor é o PR pequeno), quem pode aprovar e os prefixos de comentário.

Não é burocracia. É parar de negociar as mesmas coisas em todo PR.

Antes de você fechar a aba

Code review é o único momento em que o time inteiro conversa sobre código de verdade. É onde padrão se espalha, onde gente nova aprende rápido e onde bug morre barato.

E é também onde relação se desgasta silenciosamente, um comentário seco de cada vez, até alguém começar a aprovar tudo só pra evitar a conversa. Aí acabou o review — sobrou o carimbo.

Trinta segundos a mais escrevendo o comentário é o melhor investimento de tempo que existe no processo.

Agora conta: qual o comentário mais babaca que você já recebeu num PR? Ou — se tiver coragem, e eu tenho — qual foi o mais babaca que você já escreveu? Eu abro os trabalhos: já escrevi um "isso não faz sentido" às 19h de sexta e passei o fim de semana inteiro me arrependendo. 🙈

---