Melhores exemplos de comentários de code review (com o que fazer e o que evitar)
Edvaldo Freitas
Um único comentário em um code review pode travar um pull request por dias. A sugestão pode estar correta, mas se for pouco clara ou parecer uma ordem jogada de cima, nada vai andar. Todo mundo já viu boas intenções virarem discussões frustrantes que atrasam o time inteiro. Escrever bons comentários em uma revisão de código é uma habilidade que te deixa mais eficaz. Você aprende a melhorar o código sem quebrar o fluxo de quem escreveu ou gerar trabalho desnecessário. Nesse post vou trazer alguns exemplos de comentários de code review que vão te ajudar.
O problema com comentários no review
O review deveria acelerar a entrega ao pegar problemas cedo, mas muitas vezes acontece o contrário. Feedback vago como “refatora isso” força quem escreveu a adivinhar o que o revisor quis dizer, levando a retrabalho ou a uma reunião que quebra o ritmo. Comentários que soam pessoais, mesmo sem essa intenção, colocam o autor na defensiva. Um “isso está errado” seco passa uma impressão bem diferente de “acho que isso pode não cobrir o caso em que o usuário está deslogado. O que você acha?”. E comentários sem contexto deixam quem escreveu sem entender por que a mudança foi pedida, transformando um momento de aprendizado em algo mecânico, só para cumprir tabela.
Uma forma diferente de pensar sobre comentários
Um processo de code review é uma conversa, uma forma de construir entendimento compartilhado sobre uma mudança. O objetivo é garantir que o código está correto e que alguém além de quem escreveu consegue manter aquilo. Quando alguém deixa um comentário, está transferindo conhecimento sobre um edge case, uma limitação do sistema ou um requisito futuro que talvez não estivesse claro. Quando quem escreveu responde, compartilha o contexto por trás da decisão. Essa troca melhora a qualidade do código e deixa o time mais preparado. Cada comentário vira uma oportunidade de aprendizado para quem escreve e para quem revisa.
Exemplos de comentários de code review: o que fazer
Bons comentários são colaborativos. Eles abrem espaço para discussão, e não encerram ela.
Comece com perguntas, não com comandos
Uma pergunta respeita a autoria e reconhece que pode existir contexto que você não tem. Ela abre diálogo.
Em vez de:
"Adiciona um null check aqui."Tente:
"O que acontece se `user.profile` for null aqui? Estou pensando em usuários recém-criados que ainda não completaram o perfil. Faz sentido tratar esse caso?"Em vez de:
"Divide essa função."Tente:
"Essa função parece buscar os dados e depois transformá-los. Será que dá para separar isso em duas funções? Pode facilitar testar a parte de transformação isoladamente."Explique o “porquê” da sua sugestão
Conecte seu feedback a um princípio, um plano futuro ou um padrão do time. Isso faz a sugestão parecer objetiva, não uma opinião pessoal.
Em vez de:
"Usa `map`."Tente:
"Trocar esse `for` por um `map` pode deixar mais idiomático para criar um novo array a partir de outro. Também bate com o padrão que usamos nos outros módulos de serviço."Em vez de:
"Cria uma função helper."Tente:
"Mover essa validação para uma função helper pode evitar repetição. O ticket de `feature-Y` vai precisar da mesma validação, então daria para reaproveitar."Ofereça alternativas específicas e acionáveis
Se você vê uma abordagem melhor, mostre. Isso ajuda mais do que só apontar o problema.
Em vez de:
"Não chama esse serviço direto."Tente:
"Em vez de chamar `ServiceA.get()` direto, e se usarmos `ServiceB.fetchData()`? Esse método já tem cache e retry, então evita duplicar isso aqui."Olhe para padrões e implicações, não só uma linha
Dá um passo para trás e olha o todo. Um comentário que melhora o design do sistema vale mais do que um que só corrige um detalhe.
Em vez de:
"Tem código repetido na linha 42 e 98."Tente:
"Estou vendo esse padrão de autenticar a request e depois extrair o user ID em alguns pontos desse PR. Talvez dê para criar um middleware ou decorator para isso? Pode deixar mais limpo e consistente."O que evitar nos seus comentários
Tão importante quanto saber o que fazer é saber o que evitar. Esses hábitos só geram ruído.
Comentários vagos ou genéricos
- “Isso está ruim.” (Por quê? Qual o impacto?)
- “Refatora isso.” (Refatorar como? Qual é o problema específico?)
- “Está estranho.” (O que exatamente está estranho? Nome? Estrutura? Lógica?)
Comentários que tratam preferência pessoal como regra
Se não está no guia do time e não impacta o funcionamento do código nem a legibilidade, provavelmente é só preferência. Forçar isso gera retrabalho sem ganho real.
- “Eu sempre uso aspas simples aqui.” (Se o linter não liga, deixa passar.)
- “Não gosto dessa estrutura, muda.” (Falta o “porquê”. É mais difícil de manter? Pior performance? Se não, é só uma opinião.)
Comandos prescritivos sem explicação
Dizer o que fazer sem explicar tira a chance de aprendizado e pode soar desrespeitoso.
- “Troca isso por um `switch`.” (Por quê? Fica mais legível? Melhor performance aqui? Ou é só estilo?)
- “Usa factory pattern aqui.” (Por que esse padrão faz mais sentido nesse caso? Que problema futuro resolve?)
Ignorar o contexto por detalhes pequenos
Priorize seu feedback. Um PR com risco de N+1 não precisa de cinco comentários sobre espaço no final da linha. Em geral, siga essa ordem: primeiro, corretude — o código funciona e cobre edge cases? Depois design — encaixa no sistema e é fácil de manter? Por fim, estilo — segue os padrões do time? Se tiver um problema sério de design, começa por ele.