Cultura de revisão de código e boas práticas para PR

A revisão de código não é policiamento — é como as equipes aprendem juntas, transferem responsabilidades e mantêm a qualidade alta. Uma boa cultura de revisão fortalece toda a equipe; uma cultura ruim cria gargalos e ressentimento.

1) Mantenha-o pequeno (com menos de 400 linhas, se possível). 2) Escreva uma descrição clara: por quê, o quê e como testar. 3) Vincule o chamado. 4) Adicione capturas de tela ou vídeos para alterações na interface. 5) Faça uma autorrevisão das suas alterações antes de solicitar revisores.

Use os mesmos prefixos convencionais das confirmações: feat: add user profile page, fix: handle 404 in fetch wrapper, refactor: extract Avatar component. Muitas equipes geram registros de alterações a partir deles.

A maioria das equipes usa um modelo de PR — instale-o em .github/pull_request_template.md.

Antes de solicitar revisores, percorra suas próprias alterações linha por linha. Adicione comentários explicando escolhas que não sejam óbvias. Muitas vezes, você encontrará seus próprios erros antes que outra pessoa precise fazer isso.

Um PR de 2.000 linhas raramente recebe uma revisão completa. Divida-o em: 1) refatoração (sem mudança de comportamento), 2) novo comportamento, 3) acabamento da interface. Cada parte fica mais fácil de revisar e desfazer.

Formule como perguntas, não como ordens: “O que você acha de extrair isto para um gancho?” é melhor do que “extraia isto”. Diferencie o que precisa ser corrigido do que seria apenas desejável. Use os prefixos: nit:, question:, blocker:.

“Isto é confuso” não diz nada ao autor. “Tive de ler isto três vezes para entender o retorno antecipado — poderíamos extrair uma cláusula de proteção?” dá à pessoa algo concreto para fazer.

Comente positivamente soluções inteligentes, bons nomes e testes úteis. Isso incentiva esses padrões e suaviza o restante do feedback. PRs que recebem apenas críticas parecem hostis.

O Prettier cuida da formatação. O ESLint cuida do estilo. Não desperdice ciclos de revisão discutindo tabulações e espaços. Se uma regra de estilo continua aparecendo, codifique-a no analisador de código.

Os testes também são código. Certifique-se de que o código novo tenha testes. Verifique se os testes realmente exercitam a coisa certa — muitos testes passam mesmo quando há algo quebrado porque verificam a coisa errada.

Responda a todos os comentários — nem que seja apenas com um emoji de sinal positivo. Conteste as sugestões das quais discorda (foi você quem escreveu o código; talvez tenha informações importantes). Marque os tópicos resolvidos como resolvidos. Atualize a descrição do PR se o escopo mudar.

Revise dentro de um dia útil. PRs parados perdem contexto — o autor já seguiu adiante e o ramo precisa ser atualizado com a base mais recente. PRs grandes que ficam parados por uma semana sempre se transformam em mesclagens infernais.

O recurso de sugestões do GitHub permite que o autor aceite uma correção com um clique. É muito mais rápido do que escrever “altere esta linha para X” em prosa.

Aprove quando: o código estiver correto, os testes passarem, você entender a alteração e for seguro mesclá-la. Aprovar significa que você também assume responsabilidade pelo resultado. Não aprove mecanicamente — se não leu, diga isso.

Qual é a atitude recomendada ao dar feedback de revisão de código sobre algo que você escreveria de outra maneira?

Autor: PRs pequenos e bem descritos, com capturas de tela e testes. Faça uma autorrevisão primeiro. Revisor: feedback construtivo em forma de perguntas. Diferencie bloqueios de observações menores. Elogie o que estiver bom. Ignore o estilo — deixe as ferramentas cuidarem disso. Revise dentro de um dia. Aprove somente quando entender. Os modelos de PR padronizam o processo. Revisões são colaboração, não policiamento.