Você faz as alterações solicitadas, você melhora a aplicação, adiciona recursos ou conserta aquele bug que ninguém estava conseguindo resolver. Você envia a solicitação de pull pra frente, cheio de confiança no trabalho realizado… e ela volta lotada de feedbacks. No projeto, você é conhecido como o sujeito que ninguém quer revisar o pull request, fica aquele climão na firma, na hora do café até te evitam. O que está acontecendo aqui? Sua carreira de desenvolvedor é uma fraude?
Nada disso. Muito provavelmente você está cometendo erros bobos na hora de enviar seu pull request, gastando o tempo dos outros e achando que está abafando. Muita calma nessa hora! Seu problema é bem fácil de resolver, basta um pouco de atenção e algumas dicas.
Peter Lynch é um desenvolvedor australiano full stack com múltiplos interesses: produtividade, programação, empreendedorismo, marketing, desenvolvimento web, autodidatismo, finanças e aperfeiçoamento pessoal. Ele é o autor de “Como construir um plano para aprender a codificar com sucesso: um guia passo a passo“, já republicado por nós. Em um novo artigo publicado na internet, ele revela seus segredos para gerar pull requests que deixam todo mundo feliz, inclusive você.
Com sua autorização, traduzimos e reproduzimos o artigo na íntegra:
“Quando comecei meu primeiro trabalho, lutei para conseguir fazer bons pull requests (PRs). No começo, eu não tinha ideia do que colocar em um PR ou por que você precisava escrever um. Eu pensei que você acabou de enviar seu código como um PR e, em seguida, a pessoa que estava revisando faria o resto. Parecia direto.
Cara, eu estava errado, porque sempre que eu enviava um PR ele explodia com comentários (muitos comentários). Isso levaria à refatoração, que levaria a mais comentários, levando a mais refatoração e assim por diante. Até que, uma semana depois, estava finalmente está pronto e eu ficava me sentindo exaurido.
Não era uma sensação de alívio. Uma vez que o PR é fechado e acontece o merge, eu fico com raiva. Com raiva por desperdiçar o tempo das pessoas, com raiva por ter chegado a essa posição e com raiva por eu deixar isso acontecer mais de uma vez.
A boa notícia é que meus PRs melhoraram muito. Agora estou recebendo comentários neles acima do nível de um Lint. Na verdade, agora estou ansioso para que outros desenvolvedores vejam meu código e acho que eles gostam de ler meus PRs (tanto quanto possível).
Este artigo vai ajudar a melhorar a forma como você escreve e gerencia seus PRs, você vai ficar tão bom que eles vão trazer alegria para quem os lê. No entanto, você pode estar se perguntando: por que desejar despertar alegria em seu PR?
Por que você deve melhorar seus PRs para que eles despertem alegria
Melhorar as revisões de código não apenas ajuda você, mas também ajuda outras pessoas a ajudá-lo. Aqui estão os principais benefícios que você obtém ao escrever PRs melhores:
Você mostrará que valoriza o tempo dos membros de sua equipe: o tempo é um recurso não renovável. Sabendo disso, você quer consumir o tempo dos membros de sua equipe, tratando-os como seu lixo pessoal? Você deve valorizar o tempo de seus revisores, tornando suas relações públicas um prazer e não servindo-lhes um grande prato de código de espaguete.
Menos tempo refatorando, mais tempo construindo: quanto menos rodadas de feedback, mais tempo você tem para pegar tarefas e, portanto, construir sua reputação e habilidades. Reputação e produção aprimoradas geralmente levam a benefícios tangíveis, como mais dinheiro (quem não ama dinheiro?).
Melhora seu aprendizado: se os revisores estiverem gastando menos tempo como seu controle de qualidade pessoal, eles poderão prestar mais atenção às áreas de crescimento para você. Em vez de apontar erros desleixados, eles poderão apontar maneiras para você escrever um código melhor.
Agora você sabe o porquê, vamos ver a parte difícil: o como.
Como escrever pull requests melhores
Tenha uma lista de verificação
No início você vai cometer erros em seus PRs. Uma ou duas vezes está tudo bem, mais do que isso e você está sendo rude.
Se seus colegas continuarem apontando os mesmos erros em seus PRs, como deixar console.logs em seu código ou não seguir as convenções de nomenclatura acordadas, adicione esse erros a uma lista de verificação. Em seguida, você percorre a lista de verificação todas as vezes antes de enviar seu PR.
Abaixo está minha lista de verificação como está agora. Esta é uma lista de verificação viva e real que eu atualizo continuamente:
- Console.logs
- Convenções de nomenclatura
- Comentários não utilizados
- CSS não utilizados
- Design patterns devem coincidir com o resto do código
- Não usar if else
É inevitável que você envie um PR com erros desleixados nele. Não se preocupe, apenas adicione esse erro à sua lista de verificação. Preste também muita atenção a qualquer padrão de erros que você esteja cometendo e adicione-os à lista. A chave é não deixar erros acontecerem com frequência, porque isso diz ao seu revisor que você não valoriza o tempo dele.
Acredito que seja uma boa ideia adicionar as próximas técnicas à sua lista de verificação, mas vamos analisá-las antes de fazer isso.
Antes de enviar, dê uma volta e retorne com a cuca fresca
Antes de enviar qualquer PR eu me afasto do código, pelo menos por algumas horas, idealmente eu durmo nele.
Quando você voltar no dia seguinte, seu código ficará muito diferente. Você pode até se perguntar quem escreveu esse lixo (foi você!). Tudo bem, você quer isso. Se você se esforçar para entendê-lo no dia seguinte, imagine como seu revisor se sentiria.
Agora é sua chance de corrigir esses erros bobos e tentar torná-lo mais legível.
Dica profissional: ao revisar seu código, finja que você é outra pessoa da equipe. Use as ferramentas que eles usariam para revisar seu código, como o verificador de diferenças, e tente verificar as coisas que eles percebem com frequência em seu código. Por exemplo, um dos membros da minha equipe é um defensor de palavras em blocos de teste, então quando eu finjo ser ele, eu passo e verifico isso primeiro. É incrível o que eu pego.
Escreva um código que se explique
Seu código deve ser escrito para que as revisões não precisem fazer perguntas como “o que essa função está fazendo?”.
Mesmo que você consiga explicar o que a função está fazendo quando alguém pergunta no PR, o que acontece quando alguém precisa entendê-la sem o contexto do PR?
Portanto, se o seu código for difícil de seguir, ele precisa ser reescrito. No mínimo, precisa ter comentários explicando isso.
Se você não tiver certeza de como escrever a função de maneira legível ou não puder explicá-la de forma sucinta usando comentários, não há problema em comentar em seu PR dizendo exatamente isso. PRs são um lugar para gerar discussões, o objetivo do PR é gerar o melhor resultado para todas as partes envolvidas.
Se você for fazer isso, certifique-se de explicar o que tentou e por que optou por essa abordagem no final. Torne mais fácil para os revisores dar-lhe uma melhor orientação e, em seguida, implemente isso.
Tenha uma lista de alterações
A lista de alterações é uma maneira simples de comunicar ao revisor o que você mudou e fornecer a eles qualquer contexto de fundo de que eles precisem.
Tente pensar no futuro ao escrever uma lista de alterações. Imagine que você é alguém daqui a 2 anos que precisa atualizar essa parte da base de código. Esse futuro leitor deve ser capaz de entender o contexto da mudança.
Meu mentor diz que “uma boa lista de alterações é aquela que explica o quê e o porquê”. O quê é o que essa mudança alcança e o porquê é por que você está fazendo essa mudança. Deve-se então listar o que especificamente foi alterado.
Você também pode melhorar muito sua lista de alterações usando capturas de tela e vídeos. Afinal, uma imagem vale mais que mil palavras.
Economize tempo dos seus revisores mostrando a eles imagens antes e depois de qualquer alteração visual e mostre a eles como fica em diferentes tamanhos de tela. Use o vídeo para dar a eles uma demonstração do novo comportamento no aplicativo. Ajude-os a ajudá-lo.
Finalmente, inclua quaisquer links relevantes na lista de alterações, abaixo estão alguns que são úteis:
- Link para arquivos de design
- Link para qualquer discussão fora da ficha, por exemplo, uma discussão no slack com um designer concordando com as alterações
- Link para o ticket da tarefa
- Link para quaisquer ADRs relevantes
Mantenha o PR no escopo
Fugir do escopo é o inimigo mortal dos PRs.
Estou falando sobre esses pequenos problemas de interface do usuário que você percebe, que você acha que pode consertar rapidamente. Bem, essas pequenas mudanças na interface do usuário agora atrapalharam a revisão e seu revisor tem que gastar energia pensando sobre o que eles deveriam estar revisando.
Eu sei que é tentador fazer essa mudança rápida, mas essa mudança altera o propósito do PR. É melhor fazer um novo ticket que corrija o problema da interface do usuário, para que seu revisor possa revisar o código que deveria estar revisando isoladamente.
A fluência do escopo é complicada, é difícil resistir e não fazer essa tal pequena mudança. Entretanto, seu revisor agradecerá quando chegar a hora de revisar seu PR, porque eles não precisam mudar de contexto enquanto revisam seu código.
Como lidar com um PR após o envio
Mesmo PRs bem escritos não terminam depois que você clica em enviar. Eles ainda estão sendo escritos até você apertar o botão de mesclagem. Portanto, para escrever um bom PR, você precisa lidar com tudo até que você faça o merge e feche o PR.
Verifique seu ego
Não leve o feedback para o lado pessoal. Seu código não é você. Você precisa ser adulto ao receber feedback. Não fique bravo ou tome isso como um ataque pessoal (mesmo que seja um). No final do dia, você está no controle de uma coisa: você mesmo e como você responde. Você não pode controlar como os outros se comportarão em seu PR.
Se o feedback não for claro, verifique o ego e solicite esclarecimentos de uma maneira agradável. Tente algo como: “bom ponto e acho que entendi você. Por favor, apenas esclareça seu ponto sobre X”. No final das contas, a outra pessoa está apenas tentando melhorar seu código (alguns apenas fazem isso melhor do que outros… desenvolvedores!).
Muitas vezes o feedback é um presente. Pode ser realmente positivo quando seu revisor detecta problemas obscuros em seu código. Por quê? Porque mostra que você está escrevendo seus PRs em alto nível. Quando seu revisor pode passar por problemas óbvios, eles passam seu tempo focando em problemas reais, como lógica, design e casos extremos, o que resulta no feedback que você realmente deseja.
Certifique-se de responder a quaisquer aprendizados que seu revisor tenha tido a gentileza de lhe dar com gratidão. Se eles dedicaram um tempo para lhe ensinar algo, certifique-se de responder de uma maneira que demonstre sua gratidão.
Refatore rapidamente
Drake tem uma linha na música One Dance: “assim que você ver o texto, me responda”. Eu gosto de mudar e cantar assim para mim mesmo “assim que você vir o feedback, refatore-me”.
A melhor maneira de mostrar ao seu revisor que você valoriza o tempo dele é ser eficiente no tempo de resposta. Você faz isso acionando o feedback deles rapidamente.
Por que isso é importante? É importante porque reduz a necessidade de seus revisores se familiarizarem com seu código.
Veja do ponto de vista deles. Se você revisar o PR deles, fornecer feedback e não ouvir deles até alguns dias depois, é provável que você tenha esquecido o que o código que eles escreveram e por que você deixou o feedback. Então você essencialmente tem que revisar o código duas vezes.
Ao responder rapidamente, você reduz a necessidade de seu revisor ter que revisar o código novamente, o que significa que ele se concentra apenas no código que você refatorou.
Agora, há uma coisa a ter em mente com isso: às vezes você precisará deixar tempo suficiente para que outros revisem o código. Você não quer estar constantemente refatorando se houver discordâncias no feedback.
A maneira como abordo é garantir que pelo menos dois revisores deixem comentários antes de fazer qualquer alteração no código. Assim que eu tiver pelo menos dois desenvolvedores que revisaram o código, farei rapidamente as alterações necessárias para manter o PR avançando.
Este é um julgamento e depende de como sua equipe trabalha. Eu diria que uma boa regra geral é: com mais de 24 horas entre o feedback e a refatoração, você está dificultando a vida do seu revisor.
Comunique alterações
À medida que leio mais PRs bons, noto um padrão superior de comunicação quando são feitas alterações. Esse padrão é comunicar explicitamente uma vez que as mudanças tenham sido feitas, onde elas foram feitas e que estão prontas para outra rodada de revisões.
O revisor não precisa adivinhar se suas alterações foram feitas e se estão prontas para a próxima rodada de revisões. Assim, você está valorizando o tempo dos revisores. Ajudando-os a evitar a reavaliação do código pela metade.
Isso também economiza tempo dos revisores, pois eles não precisam pesquisar onde as alterações foram feitas, eles podem clicar rapidamente no seu link e ir direto para a revisão dessa seção de código.
Também ajuda a garantir que você marque o feedback como resolvido assim que estiver. Dessa forma, todos sabem que não há necessidade de analisar mais esse problema, o que significa que o revisor pode aprovar o código e você pode mesclá-lo.
Por fim, certifique-se de comunicar que fez alterações e que o PR está pronto para outra rodada de revisões em um canal público.
Não se estresse
Você aprenderá muito com seus colegas seniores. Ao mesmo tempo, você precisa entender que eles também podem estar errados, assim como você escreverá um código que está errado e precisa ser corrigido. Nessas situações, você precisará desenvolver habilidades de julgamento, compreensão e persuasão para navegar com habilidade.
É humano querer reagir aos erros dos revisores, especialmente se você levou surras em seus PRs. Eu senti a frustração, aquela sensação de que você está sendo alvo. Ainda assim, não tome esse erro como um desrespeito pessoal.
O importante aqui é que você tome o caminho certo (como em “não seja um idiota”). Na verdade, é uma boa chance de refletir sobre seu código novamente. Se o revisor estiver confuso, talvez seu código não esteja claro o suficiente. Aproveite para melhorar seu código, ou deixe comentários que deem clareza.
Conclusão
Escrever bons PRs é difícil, especialmente quando você está apenas começando. Ao se preparar para escrever seu próximo PR, lembre-se do que você controla, não há necessidade de se apressar em terminar o trabalho para enviar o PR.
Comece examinando o código com novos olhos, revise sua lista de verificação e lide com quaisquer erros desleixados antes de desperdiçar o tempo dos revisores. Remova qualquer coisa que não esteja no escopo e deixe-a de lado para mais tarde. Em seguida, verifique se o seu código se explica, se não o abordar no PR. Finalmente, escreva uma lista de mudanças estelar que mostre o quê e o porquê das mudanças.
Seu trabalho não está concluído depois de enviado, você precisa abordar qualquer feedback em tempo hábil e, em seguida, comunicá-lo explicitamente. Se você seguir o acima, estará no caminho certo para escrever PRs melhores que despertem alegria em seus revisores.”
Publicado originalmente como “How to write and manage PRs that spark joy” em 7 de abril de 2022. Traduzido e republicado com autorização do autor.
