Não faltam textos sobre revisão de código por aí. Mas, ainda assim, gostaria de compartilhar com vocês as lições que aprendi sobre essa prática que considero uma das mais importantes em um processo de desenvolvimento de software: a revisão de código.

Se você chegou aqui sem saber exatamente o que é revisão de código (code review em inglês) te dou uma ideia:

É uma etapa no desenvolvimento de software onde uma ou mais pessoas do time, que não é a pessoa que desenvolveu, revisa uma modificação ou nova funcionalidade antes desta ser incorporada ao código atual.

O objetivo dessa etapa é detectar possíveis erros ou inconsistências, além de compartilhar conhecimento com outras pessoas do time a respeito de modificações no código do projeto. As inconsistências podem variar de estilo do código até regras de negócio ou efeitos colaterais da mudança.

Ao longo da minha experiência profissional como desenvolvedora, que considero ter começado de verdade há 4 ou 5 anos atrás, nas empresas por quais passei tive experiências diferentes. Em algumas, a revisão de código era só para dizer que outra pessoa passou o olho no código, mesmo sem ter entendido bem; em outra, a revisão de código era elaborada, incluindo testes manuais da branch em questão. Nesse texto relato o que considero boas e más práticas na revisão de código.

Hora de revisar!

Alguns pontos para quem está revisando código.

Deixe a revisão mecânica para as máquinas

Tópicos como estilo de código são pessoais. Quantas discussões você já não deve ter visto sobre espaços ou tabs? Ou sobre aspas simples ou duplas? Esse tipo de discussão não deve ser trazido a cada novo pull request (solicitação de mudança). O time deve concordar em um estilo e ser guiado por ele. E esse estilo deve ser controlado por máquinas e não por humanos. Isso pode se dar de várias formas, como:

• pre-commits: antes de permitir que você crie um novo commit, um hook irá checar a ordem os imports, se tem linhas com chamadas de debug, excesso de espaços em branco, imports não utilizados etc. Você só poderá criar um commit se o seu código estiver de acordo com as regras estabelecidas pelo projeto. Um exemplo de configuração de pre-commit aqui.
• configurações no seu editor de texto: ter essas configurações no seu editor de texto também é uma boa maneira de fazer com que essas boas práticas sejam lembradas sem grande esforço.
• linters no CI: linters são programas que checam esses estilos ou regras. Você pode colocá-los em uma etapa na sua ferramenta de Continous Integration (CI). Todas as vezes que alguém abrir um pull request os linters serão executados e a ferramenta indicará se houve falha ou não. Um exemplo de CI com linters no Github Actions aqui.

Outros exemplos podem ser encontrados no meu texto Melhorando a Qualidade do Código junto com o time. Para que essas automações sejam possíveis o time deve concordar em um guia de estilo e no processo para incorporação de novas modificações no código do projeto.

O ponto mais importante aqui é: esse tipo de trabalho deve ser feito por máquinas e não por humanos. Ao invés de ficar pensando sobre espaços ou tabs, a pessoa que revisa o código deve estar livre para focar em aspectos mais profundos, como arquitetura e regras de negócios.

Tenha empatia com o autor

Empatia é uma das habilidades mais valiosas em desenvolvimento de software. Te ajuda a ter um melhor relacionamento com seu time e a entender quais problemas resolver para o seu usuário. Infelizmente é uma habilidade difícil de desenvolver e requer intenção e prática constante. Se não temos isso em mente, é muito fácil esquecer como é ser um iniciante ou, simplesmente, um humano. Então, pessoa revisora, não esqueça:

Você está revisando o código de outro humano, que tem sentimentos, expectativas e defeitos.

Como exercer essa habilidade na prática? Alguns conselhos:

• Seja gentil ao escrever. O texto sozinho pode por vezes soar frio ou áspero.
• Pergunte o que a pessoa acha.
• Valorize as coisas legais que ela fez.
• Tente explicar os motivos para solicitar determinada alteração.
• Procure entender as decisões por trás. Perguntar não ofende.

Você pode ser a pessoa que ninguém quer revisando o código ou alguém que faz o processo de revisão ser valioso. Eu tive uma pessoa no time que todos queriam ter seu código revisado por ela. Simplesmente porque ela sempre tinha algo interessante pra acrescentar: sobre o impacto em outras partes do código, no negócio ou na arquitetura. Sou uma grande fã dela, na real :). Isso era possível graças ao conhecimento técnico mas, sobretudo, pela empatia. Ela investia tempo em entender a modificação e propor alternativas.

Não pode ter preguiça

Muitas revisões resultam em idas e vindas mas não pode ter preguiça e aceitar incorporar as alterações de qualquer jeito. É pouco provável que alguém volte e conserte. Se for o caso, registre a dívida técnica ou bug antes e depois continue a revisão. O importante é ter um entendimento entre você, revisor, e o autor da mudança.

Ao falar disso me lembrei de um líder técnico que, durante um evento de recrutamento, se gabava de reescrever as alterações das pessoas do seu time quando ele não gostava da solução. Imagine a loucura! Além de perder muito tempo reescrevendo o código, essa pessoa também deixava de investir tempo no desenvolvimento das pessoas do time em que era líder. Ao ouvir isso eu aproveitei para sair correndo dessa empresa.

Entenda o código que está revisando

Ler um código que não é seu e entender é uma tarefa difícil que fica mais tranquila conforme você tem intimidade com o código do projeto como um todo. Revisar um código que você ainda não tem intimidade requer mais esforço. Comece lendo a descrição da modificação e a estória. Tente seguir a modificação: ela vem de um campo em um formulário? De uma rotina que é executada quando uma informação cai no banco de dados? E aí, o que vem depois? Seguir esse “fio” ajuda na hora de ler o código em si. Você vai olhar para o código com o contexto do problema a ser resolvido em mente e não apenas com o contexto da tecnologia.

Ao entrar na Thermondo, encontrei um processo de revisão de código onde as pessoas faziam checkout da branch localmente para ver a modificação funcionando. Isso estava escrito em algum lugar? Não. Alguém me falou que era obrigatório fazer? Não também. Isso mudou o jogo para mim. Gasta mais tempo? Sem dúvidas. Mas me ajudou muito a entender melhor as mudanças propostas, cumprindo o propósito de compartilhamento de conhecimento trazido pela revisão de código. Eu passei a testar a modificação localmente e depois revisar o código. Senti que fiquei mais produtiva nas revisões de código após adotar essa rotina.

Prazo para revisão

Em uma das empresas que trabalhei tínhamos até 24 horas para revisar os pull requests. Funcionava bem para a gente (na época, um time entre 7 e 10 desenvolvedores). O ponto importante de ter um prazo para revisão é não deixar o código envelhecer e evitar conflitos, além de permitir que a pessoa parta para outra tarefa rapidamente. Não existe número mágico para esse prazo. Você deve conversar com o seu time e ver o que funciona melhor para vocês.

Hora de ter seu código revisado!

Alguns pontos para quem está tendo seu código revisado.

Seu código está pronto?

Só peça uma revisão quando seu código estiver pronto. Para checar se ele está pronto, você pode se perguntar:

Posso incorporar esse código em produção do jeito que ele está? É a melhor versão?

Não dá para pedir revisão do código quando os testes estão quebrados, os linters estão falhando ou está faltando uma parte da funcionalidade. O tempo da pessoa que vai revisar seu código é valioso. Tenha isso em mente.

Caso você tenha aberto um pull request apenas para visualizar as alterações ou indicar que algo está em andamento, sinalize isso. No Github você pode abrir um pull request como draft (rascunho) ou apenas colocar no título um WIP (ou TEA: trabalho em andamento? :P) ou também adicionar na descrição do seu pull request que ele ainda não está pronto para ser revisado.

Por falar em descrição…

Ao abrir um pull request é importante dar um contexto. Frequentemente pull requests são utilizados como documentação de modificações. Abrir um pull request que tem 15 arquivos modificados e nenhuma descrição é frustrante. Por isso, deixe uma descrição com uma explicação do que você fez, qual o objetivo, com um link para a descrição da estória (caso tenha) ou informações adicionais (se for um bug, por exemplo, como reproduzi-lo). Caso você esteja adicionando um comando novo, por exemplo, adicione instruções de como executá-lo. Dessa forma você ajuda a pessoa que está revisando o seu código a entender melhor as modificações que você fez e evita idas e vindas na revisão com perguntas que poderiam ter sido respondidas antes.

Não é nada pessoal

É comum ter idas e vindas em revisões de código. Às vezes eu fico super ansiosa para ter uma modificação mergeada mas daí vem uma chuva de comentários. Faz parte do jogo. É importante respirar fundo e abraçar esse processo, que ajuda a construir não apenas um código melhor mas pessoas desenvolvedoras melhores. Não desanime caso aconteça com você; é normal.

Claro, vira e mexe encontramos pessoas sem empatia por aí. Eu já chorei com certos comentários que recebi em revisões. Me lembro de pelo menos duas ocasiões em empresas diferentes onde isso aconteceu. Em uma delas, a pessoa não soube que fez uma revisão ruim. Em outra, não apenas eu dei feedback a pessoa mas pessoas do meu time que viram o pull request e os comentários, mesmo eu não tendo falado nada, também fizeram. Foi algo que me surpreendeu pois não sabia que outras pessoas se importariam a esse ponto. Ninguém soube que eu chorei porque a pessoa foi escrota mas os meus colegas tiveram empatia o suficiente para entender que aquele tipo de comportamento apresentado pelo revisor não era saudável. Dar o feedback nessas situações é fundamental.

Evite abrir pull requests grandes demais

Quanto maior o pull request menor a chance dele ser revisado com cuidado. É o que diz o meu instituto de pesquisas (brincadeira, acho que li isso em um artigo mas eu não consegui achar). Caso você esteja trabalhando em uma funcionalidade muito grande e que não pode ser incorporada a master diretamente, você pode tentar:

• usar feature flags; feature flags são como interruptores para funcionalidades, que você pode ligar e desligar através do código (diretamente com um if/else ou usando uma variável de ambiente, por exemplo). Essa estratégia te possibilita manter o código incorporado a master mas desativado até que toda a funcionalidade esteja pronta.
• criar uma branch para a funcionalidade e abrir pull requests menores para essa branch base. Para isso, você deve ter organizado o que você tem que fazer. É bom discutir com o seu time a estratégia para abordar a implementação. Dessa forma, todos poderão te ajudar a pensar o melhor jeito de desenvolver uma funcionalidade e ter em mente o que você está tentando fazer.

Por hoje é só, pessoal

Sendo revisor ou tendo seu código revisado, se comunicar é fundamental. Tente passar as suas ideias e dúvidas de maneira clara. Ter um processo bem definido com o seu time e ao mesmo tempo ter a flexibilidade para mudar é fundamental para que as coisas andem bem.

Espero que esse texto tenha sido útil! Um abraço e até a próxima!