É no pull request que a senioridade aparece de verdade

Você abre e sente um frio na barriga. Quarenta e sete arquivos alterados. Duas mil linhas adicionadas. A descrição diz “resolve aquilo que a gente conversou”. Nenhum contexto sobre o que foi testado e descartado, nenhuma indicação do que olhar primeiro, só uma parede de diffs e a expectativa implícita de que você vai aprovar, porque revisar direito tomaria o resto da sua tarde.

Esse pull request te conta tudo sobre a pessoa que o abriu, e nada disso tem a ver com a capacidade dela de programar. Tem a ver com ela entender, ou não, que um pull request não é um depósito de trabalho pronto. É um pedido pela atenção e pelo julgamento de outra pessoa. Tratá-lo como detalhe depois que o “trabalho de verdade” acabou é um dos sinais mais claros de onde alguém realmente está na carreira, não importa quantos anos apareçam no currículo.

O código nunca foi a parte difícil

Uma verdade incômoda para quem acha que escrever código correto é o teto da senioridade: o código dentro da maioria dos pull requests está ok. Compila, passa nos testes, provavelmente faz o que deveria fazer. O que separa o pull request de um engenheiro sênior do de todo mundo não é a correção. É se ele tornou possível o trabalho de quem revisa.

Um engenheiro júnior otimiza para terminar a tarefa. Um engenheiro sênior otimiza para o custo total da mudança, e esse custo inclui cada minuto que outra pessoa gasta tentando entender o que aconteceu e por quê. Essa virada, de “isso está pronto?” para “alguém consegue aprovar isso com segurança num tempo razoável?”, é um dos marcadores reais de senioridade. E quase nunca alguém a nomeia diretamente, porque não é uma habilidade que alguém coloque no currículo.

O escopo é o primeiro sinal

O maior sinal em qualquer pull request é se ele faz uma coisa só. Não um commit só: uma coisa só. Um engenheiro sênior que percebe, no meio de um fix, que o código em volta precisa de uma limpeza quase sempre abre um segundo pull request para essa limpeza, mesmo que isso dê mais trabalho burocrático. Misturar uma mudança real de comportamento com refactoring sem relação deixa as duas mais difíceis de revisar e impossíveis de reverter separadamente se algo quebrar.

O instinto de juntar tudo num pull request só porque “eu já estava mexendo ali” é compreensível e quase sempre errado. Ele otimiza para quem escreve o código, que tem todo o contexto na cabeça agora, à custa direta de quem revisa. Essa pessoa precisa reconstruir o contexto do zero e ainda segurar duas mudanças sem relação na cabeça ao mesmo tempo para avaliar qualquer uma delas direito.

A descrição faz trabalho de verdade, ou não faz

A maioria das descrições de pull request repete o diff em prosa. “Este PR adiciona uma camada de cache ao serviço de usuários.” O revisor já sabe disso: ele está olhando o código. Uma descrição que realmente serve responde perguntas que o diff não responde: por que agora, que alternativa você considerou e descartou, o que tem de arriscado nesta mudança específica e onde o revisor deve concentrar sua atenção limitada.

Esse último ponto importa mais do que as pessoas costumam reconhecer. Dizer a um revisor “a lógica de retry no terceiro arquivo é a parte de que tenho menos certeza” não é admitir fraqueza. É respeitar o tempo dele, apontando esse tempo para onde ele é mais necessário, em vez de obrigá-lo a aplicar o mesmo rigor a trezentas linhas quando duzentas e oitenta são mecânicas.

Histórico de commits é ferramenta de comunicação, não diário

Um histórico de commits que diz “wip”, “fix”, “agora vai”, “remove console.log” é um diário privado de como o trabalho aconteceu, e deve continuar privado: com squash ou limpo antes de chegar a um revisor. Apagar esse histórico não é desonesto. Ele nunca foi feito para ninguém além de quem o escreveu.

Um histórico de commits que se lê como uma sequência de passos intencionais e revisáveis (extrair a interface, implementar o novo provider, conectá-lo aos pontos de chamada existentes, remover o provider antigo) faz algo que um diff sozinho não faz. Ele deixa o revisor aprovar a mudança na ordem que faz sentido lógico e pegar um problema no passo dois sem precisar entender ainda o passo quatro. Montar essa estrutura depois do fato exige esforço deliberado, e pular esse esforço é uma das formas mais comuns de um trabalho de nível sênior ser lido como júnior na revisão.

O que uma boa cultura de revisão custa de verdade

Nada disso funciona se a equipe não tratar o tempo de revisão como trabalho de verdade, e não como algo espremido entre reuniões. Se a expectativa é que os revisores aprovem coisas em minutos, entre outras obrigações, os engenheiros vão aprender, com razão, que um pull request menor e mais limpo não é revisado mais rápido do que um enorme e bagunçado, porque ninguém tem tempo de ler nenhum dos dois com cuidado. Nesse ambiente, o incentivo para montar um pull request limpo, com escopo definido e bem descrito some em silêncio, não importa quantos posts de blog a equipe tenha lido sobre o assunto.

Resolver isso não passa por escrever um template melhor de pull request. Passa por um acordo explícito da equipe de que revisão é trabalho agendado, com tempo real reservado para ela, e não algo encaixado nas brechas de uma agenda já lotada de reuniões. Equipes que protegem o tempo de revisão veem a qualidade dos pull requests melhorar sozinha, porque os engenheiros param de achar que enquadrar bem a mudança é esforço desperdiçado que ninguém vai ler.

O lado do revisor nesse acordo

Nada disso é uma obrigação de mão única. Um revisor que deixa um “LGTM” num pull request de quarenta arquivos sem ler não está sendo eficiente: está empurrando o risco para quem encontrar o bug em produção três semanas depois. E um revisor que fica implicando com nomes de variáveis num pull request que nunca deveria ter ficado desse tamanho está resolvendo o problema errado. O problema era o escopo, não os nomes, e nenhuma quantidade de comentários sobre nomes resolve isso.

Um bom revisor pede para dividir o pull request antes de mergulhar em comentários de linha quando ele tenta fazer coisas demais de uma vez. Esse hábito, questionar o escopo antes de revisar o conteúdo, faz mais pela qualidade do código de uma equipe ao longo de um ano do que qualquer quantidade de comentários cuidadosos, linha por linha, em pull requests que nunca deveriam ter existido no formato atual.

Como isso fica na prática

Nada disso exige um processo formal ou uma ferramenta nova. Exige um hábito: antes de abrir um pull request, pergunte se alguém sem nenhum contexto sobre o que você estava fazendo conseguiria entender o que mudou e por quê nos primeiros dois minutos de leitura. Se a resposta honesta for não, a solução geralmente não é escrever uma descrição mais longa. Muitas vezes é dividir a mudança, reordenar os commits ou cortar escopo até a resposta virar sim.

Esse hábito custa alguns minutos a mais por pull request. E economiza horas de tempo de revisão em toda a equipe, semana após semana, de um jeito que nunca aparece numa retro de sprint, mas aparece o tempo todo na velocidade com que a equipe realmente entrega.

A discussão sobre tamanho que ninguém quer ter em voz alta

Toda equipe tem uma tolerância não oficial ao tamanho de pull request que todo mundo aceita em silêncio e ninguém escreve em lugar nenhum. Essa tolerância normalmente é definida pelo maior pull request recente que foi aprovado sem questionamento, e ela só anda numa direção: para cima. Depois que um pull request de quinhentas linhas passa direto porque todo mundo estava ocupado naquela semana, um de trezentas linhas deixa de parecer grande em comparação, e a referência de toda a equipe muda sem que ninguém tenha decidido isso.

A solução não é um limite fixo de linhas na configuração do linter, porque o tamanho certo depende totalmente do que a mudança faz. Um pull request de trezentas linhas que adiciona uma única função bem testada, com boilerplate gerado em volta, pode ser trivial de revisar. Um de quarenta linhas que mexe nas suposições compartilhadas de cinco módulos diferentes pode levar uma hora para ser revisado direito. Tamanho em linhas é, no máximo, uma aproximação grosseira. A pergunta real é quantas coisas independentes o revisor precisa segurar na cabeça ao mesmo tempo, e esse número quase sempre deveria ser um.

Por que isso pesa mais quando a equipe é distribuída

Todo esse argumento fica mais forte no momento em que sua equipe não está na mesma sala. Numa equipe presencial, um pull request confuso se resolve com alguém indo até a mesa do outro e perguntando “espera, o que isso aqui faz?”. Entre fusos horários, um pull request confuso significa que o autor já está dormindo quando a pergunta chega, e a resposta só aparece quando o revisor já passou para outra coisa. Aí a revisão recomeça do zero no dia seguinte. Equipes que trabalham entre fusos da LATAM e dos EUA pagam esse imposto o tempo todo. As que escrevem pull requests como se o revisor não pudesse fazer uma pergunta rápida em tempo real (porque normalmente não pode) entregam visivelmente mais rápido do que as que não fazem isso.

No fim das contas

Ninguém é promovido a sênior por escrever um pull request que outra pessoa consegue revisar em cinco minutos em vez de cinquenta. Mas essa habilidade, tratar um pull request como uma peça de comunicação voltada para a atenção limitada de outra pessoa, e não como um depósito de trabalho pronto, é um dos sinais mais confiáveis de onde alguém realmente está na carreira. Ela não aparece no cargo. Aparece toda vez que você abre o diff dessa pessoa.