𝗢𝗽𝗲𝗻 𝘁𝗵𝗲 𝗣𝗥 𝘆𝗼𝘂𝗿 𝗿𝗲𝘃𝗶𝗲𝘄𝗲𝗿 𝗵𝗮𝘀 𝗻𝗼𝘁 𝗺𝗲𝘁 𝘆𝗲𝘁
I reviewed a large pull request recently. It used AI to help write the code. It changed a module that three other features used. The description was only one sentence. It named the file but not the reason for the change.
I spent fifteen minutes mapping the changes before I could start. I had to find the intent. I had to find the risks. I had to separate the important files from the noise.
I realized I had done this to someone else before.
When you write code, you carry all the context. You know why you split a module. You know what you tried first. You know which parts you feel unsure about.
Most people write descriptions for themselves. They write "Refactored service layer" or "Fixed auth module." These are descriptions for people who already know the context.
A good description is for the person who knows nothing.
A description is not just a summary. It is a test. If you cannot explain your work, your work is not ready.
I now use a six-part structure for every non-trivial PR:
• Intent: Explain why this PR exists and the problem it solves. If you cannot write this, stop. The PR is not ready. • Major changes: List decisions that affect architecture or existing behavior. • Minor changes: List cleanups and renames. Keep them separate from structural changes. • Impact: List the systems this touches. Provide a map of the blast radius. • Evidence: List what you ran and what tests you passed. Show proof that you did the work. • Uncertainties: State what you are unsure about.
When you admit uncertainty, you help the reviewer. They know where to look closely. They do not waste time on parts that are working fine.
If you cannot name your uncertainties, you have not thought deeply enough about your code.
The description is the last step before you decide if a PR should even open.
A reviewer who understands your intent spends time on hard questions. A reviewer who must guess your intent spends time on easy questions. They ask what things are instead of asking if they are right.
Write for the reviewer who has not met your code yet. Write as if you will not be there to answer questions. Write as if you are reading it three days from now with no memory of the work.
If the description holds up, the PR is ready.
Abra o PR, seu revisor ainda não o conheceu
Eu costumava ser aquele desenvolvedor. Aquele que passa horas, às vezes dias, polindo cada linha de código, refatorando cada função e garantindo que todos os testes passem perfeitamente antes mesmo de pensar em abrir um Pull Request (PR). Eu queria que meu código fosse impecável. Eu queria impressionar meus revisores com minha perfeição.
Mas aqui está o detalhe: enquanto eu estava ocupado polindo meu código, eu estava, na verdade, atrasando a parte mais importante do processo de desenvolvimento: o feedback.
Ao esperar até que o código estivesse "perfeito", eu estava perdendo insights precoces, correções arquiteturais e possíveis melhorias que poderiam ter sido detectadas muito antes. Eu estava, essencialmente, trabalhando em um vácuo, apenas para descobrir durante a revisão que eu havia tomado o caminho errado quilômetros atrás.
A verdade é que um Pull Request não é apenas um pedido para fazer o merge do código; é uma conversa. É uma oportunidade de se alinhar com sua equipe, de aprender uns com os outros e de garantir que a direção que você está tomando é a correta.
Quando você abre um PR cedo, mesmo que seja um Work In Progress (WIP), você está convidando seu revisor para o processo. Você está dizendo: "Ei, é para cá que estou indo. Isso parece certo para você?"
Esta abordagem tem vários benefícios:
- Feedback precoce: Você detecta erros e falhas arquiteturais cedo, antes que eles se tornem profundamente enraizados em seu código.
- Redução de retrabalho: É muito mais fácil mudar de direção quando você escreveu apenas 50 linhas de código do que quando escreveu 500.
- Compartilhamento de conhecimento: Isso permite que sua equipe se mantenha informada sobre o que você está fazendo, evitando silos.
- Velocidade maior: Embora possa parecer mais lento abrir PRs com frequência, isso na verdade acelera o ciclo de desenvolvimento geral ao reduzir o tempo gasto em revisões massivas e complexas.
Portanto, da próxima vez que você sentir o desejo de passar mais três horas refatorando aquela única função apenas para deixá-la "perfeita", pare. Abra o PR. Deixe seu revisor vê-lo. Deixe a conversa começar.
Seu código não precisa ser perfeito. Ele precisa estar correto. E, às vezes, a melhor maneira de acertar é deixar que os outros ajudem você no caminho.