Code Review

Guidelines para PRs: boas práticas para melhorar a qualidade do código e reduzir o tempo de revisão

Avatar photo Edvaldo Freitas

Um processo de code review lento apontam para um problema maior. Nosso processo não define expectativas claras, e o verdadeiro culpado geralmente são PR guidelines vagos ou inexistentes. Quando um pull request fica dias parado na fila, ou uma thread de review vira uma discussão de 50 comentários sobre detalhes pequenos, isso afeta mais do que aquele PR. O time inteiro perde ritmo. O impacto de verdade está na troca de contexto constante e a perda de foco que consomem o tempo de engenharia.

Onde a maioria dos times erra na hora de definir guidelines de PR

Muitos times tentam resolver isso escrevendo um documento gigantesco. E esse documento acaba virando o problema. É uma lista longa de regras, cobrindo desde sintaxe de commit até princípios de arquitetura, e os desenvolvedores deveriam decorar tudo. Ninguém olha depois da primeira semana.

Esses guias normalmente falham porque são baseados em regras rígidas que transformam o review em um checklist mecânico. Eles perdem o ponto sobre intenção compartilhada. Também ignoram como um revisor realmente trabalha. Um revisor precisa entender o porquê e o risco de uma mudança rapidamente. Um documento que só confirma que o código segue um style guide está só criando ruído.

Foco na intenção, não só nas regras

Boas guidelines de PR deveriam iniciar uma conversa. Elas dão ao autor e ao revisor uma linguagem compartilhada e um ponto de partida comum para discussão. O objetivo principal é mergear uma mudança bem entendida, com qualidade, o mais rápido possível. O resto é secundário. As guidelines devem reduzir dúvidas respondendo às primeiras perguntas do revisor antes mesmo delas aparecerem. Isso permite que o revisor use seu tempo no que realmente importa, como a lógica, arquitetura e possíveis efeitos colaterais.

Guidelines de PR que realmente ajudam

Aqui estão as guidelines que podem te ajudar. Não é uma lista completa cobrindo todos os edge cases possíveis. É um conjunto de padrões que percebemos que mantém o processo fluindo e a qualidade do código alta.

Escrevendo para o revisor: o que ele precisa entender rápido

O revisor está interrompendo o que estava fazendo para olhar seu código, então facilite o trabalho dele. A descrição do PR é a melhor ferramenta para um review rápido. Ela deve ser um resumo curto que explica o que ele vai ver. Sua descrição precisa responder quatro perguntas antes mesmo do revisor abrir o código:

  1. Qual é o contexto? Link para o ticket (Jira, Linear, etc.). Explique brevemente o problema que você está resolvendo ou a feature que está construindo. Uma ou duas frases são suficientes.
  2. O que mudou? Descreva sua abordagem. Não repita a descrição do ticket. Explique as decisões técnicas que você tomou. Por exemplo, “Adicionei um novo UserService para lidar com a criação de usuários, tirando essa lógica do controller” é muito mais útil do que “Criei a página de cadastro de usuário”.
  3. Quais são os riscos? Existem possíveis breaking changes? Isso mexe em um caminho crítico? Existe dependência do trabalho de outro time? Quando você aponta riscos, mostra que pensou no que pode dar errado.
  4. Como isso foi testado? Descreva os testes realizados. Inclua testes automatizados (unit, integração) e passos manuais. Se for uma mudança de UI, adicione um screenshot ou um vídeo curto. Evidência de teste gera confiança e poupa trabalho do revisor.

Definindo o tamanho do PR

PR grande é o principal motivo de revisores demorarem. Se quem está revisando vê um diff com +2000 linhas, ele vai adiar isso. E mesmo quando pega, a qualidade do review cai. Ninguém consegue revisar bem uma mudança desse tamanho.

Uma regra simples que você pode definir: um PR deve ser pequeno o suficiente para uma pessoa revisar bem em menos de 30 minutos.

Isso geralmente significa menos de 400 linhas de mudanças relevantes (sem contar arquivos gerados, lockfiles, etc.). Não é uma regra obrigatória, mas serve como um bom indicativo. Se o PR for maior, provavelmente é bom quebrar ele. Um refactor grande pode ser dividido em alguns PRs menores e sequenciais. Uma nova feature pode ser construída atrás de uma feature flag e mergeada em partes. A ideia é que cada mudança seja uma unidade pequena e lógica que alguém consiga entender com facilidade.

Como manter a qualidade do código sem cair em microgestão

O revisor não deveria agir como um linter humano. Checagens repetitivas e objetivas devem ser automatizadas.

  • Linters e Formatadores: Estilo de código, formatação e análises estáticas simples precisam ser automatizados e rodar no CI. Um review não deveria travar por comentários sobre posição de chaves ou ordem de imports. Se o pipeline está verde, consideramos esses checks aprovados.
  • Foco de quem está revisando: O revisor deve focar no que máquina não consegue validar:
    • O código resolve o problema certo?
    • A lógica faz sentido? Tem edge cases ignorados?
    • Isso se encaixa na arquitetura existente?
    • Existem riscos de performance ou segurança?
    • O código está claro o suficiente para o próximo dev manter?
  • AI Code Review: Podemos usar assistentes de IA para fazer uma primeira analise. Essas ferramentas são boas em encontrar bugs ou sugerir refactors em funções mais complexas. Também ajudam a identificar se está faltando testes. Isso cobre mais uma camada de trabalho mecânico, deixando as pessoas focarem no design e na lógica de alto nível.

Regras para reduzir gargalos

Para evitar que PRs fiquem travados, precisamos de expectativas claras tanto para quem abre quanto para quem revisa.

  • Ready vs. Draft: Se o PR não está pronto para revisão final, abra como Draft ou use o prefixo “WIP”. Isso indica que você quer um feedback inicial, não uma aprovação. Um PR só está pronto quando o CI está verde e a descrição está completa.
  • Assign de reviewers: Atribua pelo menos dois revisores. Um deles deve ser code owner dos principais arquivos alterados. E não adianta só atribuir — se for urgente, chama no Slack.
  • Tempo de resposta: Esperamos feedback em até um dia útil. Se não conseguir revisar nesse tempo, deixe um comentário explicando e se desatribua para o autor encontrar outra pessoa.
  • Responsabilidade do autor: O autor é responsável por levar o PR até o merge. Isso inclui responder comentários, subir ajustes e fazer o merge depois da aprovação. Não deixe seu PR envelhecer.
  • Comentários blocking vs. non-blocking: Use prefixos [blocking] ou [non-blocking]. Um blocking precisa ser resolvido antes do merge. Um non-blocking é sugestão para melhoria futura e pode virar um ticket depois. Esse hábito simples evita muita confusão.

Um template simples de PR guidelines

A melhor forma de garantir o uso é colocar o template direto no repositório (por exemplo, como PULL_REQUEST_TEMPLATE.md). Ele aparece automaticamente ao abrir um PR.

Aqui está um template que funciona bem:

### Context

<!-- Link para o ticket (Jira, Linear, etc.) e um resumo curto do trabalho -->
Ticket: [PROJ-123](https://your.jira.com/browse/PROJ-123)

### Changes

<!-- Descreva a abordagem técnica e o que mudou -->
-
-

### Risks

<!-- Existe breaking change ou algo que merece atenção especial? -->
-

### Testing

<!-- Como isso foi testado? Inclua testes automatizados e passos manuais. Adicione screenshots se for UI -->
-
-

O objetivo dessas guidelines não é criar mais uma burocracia. É montar um sistema que ajuda todo mundo a trabalhar melhor. Quando as expectativas são claras, o fluxo anda, e conseguimos entregar código mais rápido com menos erro.