Code Reviews para pessoas autoras e revisoras
O processo de revisão de código é uma das tarefas mais rotineiras quando se trabalha dentro de um time de desenvolvimento. Nele, um ou mais desenvolvedores ou desenvolvedoras revisam as mudanças de código propostas, procurando identificar possíveis melhorias de desempenho, erros na lógica de implementação ou comportamentais, boas práticas, aderência aos padrões do codebase etc. Trata-se de uma divisão da responsabilidade na execução de uma mudança no código, em que uma segunda pessoa certifica-se que o pull request (PR) criado cumpre o que é proposto de maneira correta e performática.
Quando escrevemos um código, nos sentimos mais confiantes em colocar as mudanças implementadas em produção porque alguém as revisou. Mas como podemos ajudar as pessoas que farão a revisão quando criamos um PR? E, uma vez no papel de pessoa revisora, como garantir que faremos uma boa revisão? Neste artigo, Mariana Cardoso, Paula Keiko e eu vamos dissertar sobre alguns pontos que, na nossa experiência, ajudam a responder essas perguntas.
Antes do code review
Antes mesmo de iniciar o processo de code review, há etapas que podem diminuir o trabalho tanto para a pessoa revisora quanto para a pessoa autora.
A aplicação de regras de linter pode simplificar significativamente o processo de revisão de código. Essa ferramenta realiza uma análise preliminar, identificando os padrões de codificação que devem ser adotados. Isso significa que muitos dos possíveis problemas são identificados antes mesmo da revisão humana, o que alivia a carga sobre a pessoa revisora. Por isso, é fundamental implementar essas regras para garantir uma revisão eficiente e consistente.
Outro ponto que facilita a escrita e revisão é a padronização de código. A documentação sobre padrões de codificação pode ser altamente eficaz, pois serve como um guia claro sobre as práticas de codificação a serem seguidas, prevenindo discrepâncias entre o novo código e o já existente no projeto. Essa abordagem contribui para a manutenção da consistência do código e, caso essa prática exista, é muito importante segui-la.
Escrevendo um pull request
Ao abrir um PR, costuma-se escrever um resumo do que foi feito. Um primeiro passo para facilitar a revisão das mudanças é ter cuidado ao redigir esse resumo. É importante pensar que, no futuro, alguém sem o contexto atual pode tentar entender um comportamento do produto com base nesse texto. Ou, então, pensar que uma pessoa que não tenha o contexto do seu time possa ter que fazer a revisão do seu código. Então, devemos nos questionar: quão completa está a descrição dele? Seria factível o entendimento?
Dentro do nosso time, adotamos alguns hábitos que têm nos auxiliado na tarefa de escrever um resumo mais completo. Primeiramente, buscamos explicar o contexto em que a mudança está sendo feita e quais são as consequências dela. Além disso, quando tomamos uma decisão de seguir o caminho A ao invés de B dentro do contexto do PR, explicamos o que levou a essa decisão.
Ao tratar-se de PRs em que há a criação de novos elementos visuais, uma forma de ajudar a pessoa revisora a compreender o que o código está fazendo é por meio de imagens, ou até mesmo adicionando um vídeo do comportamento na descrição. Esses elementos visuais também carregam grande valor em PRs que corrigem bugs. Porém, nesses casos, além de imagens ou vídeos, é importante contextualizar a pessoa revisora sobre o que está sendo corrigido, como está sendo corrigido e como reproduzir o problema, para que seja possível simular o mesmo fluxo antes e depois da aplicação do seu código.
Além disso, é necessário ter cuidado ao nomear variáveis e funções, de maneira que o nome delas represente o que fazem ou o que armazenam. Isso é um passo importante, pois facilita a leitura de código, não somente na revisão, mas também em futuras iterações sobre esse trecho do codebase. Outro ponto de atenção ao fazer a revisão é cobrar para que esses nomes sejam significativos, mantendo assim a qualidade do código.
Revisando um pull request (PR)
Considerando o lado da pessoa revisora, entender o contexto do PR é o primeiro passo. Só assim é possível julgar se a implementação foi feita de maneira correta ou não. Em geral, para PRs mais complexos, uma única leitura do código pode não ser o suficiente para entender tudo o que foi feito.
Muitas vezes, se faz necessário verificar o código que não foi alterado, mas está relacionado às mudanças propostas. Por exemplo, ao considerar apenas a leitura do código modificado, a percepção da mudança de um componente pode não se refletir no produto como imaginado. Mas, investigando o elemento que envolve esse componente, é possível entender o resultado final.
Outra prática que pode ajudar na revisão é realizar testes manuais, principalmente para garantir que o comportamento segue o especificado, e para garantir que temos responsividade (como o elemento se comporta em telas de diferentes tamanhos) em casos de alterações no frontend. Às vezes, o caminho é encontrar o erro no comportamento e investigar no código por que ele acontece, qual parte da implementação está errada ou qual caso de canto deixamos de tratar.
Perguntar também é parte importante na revisão de código. No momento em que se está revisando um PR, pressupõe-se que a pessoa com mais conhecimento de comportamento e contexto do que foi modificado é a própria autora das mudanças. Por isso, faz sentido que todas as dúvidas que um revisor ou revisora tenham sejam direcionadas a essa pessoa, podendo assim facilitar a revisão ou levantar um ponto que passou despercebido.
Além disso, há diferentes tipos de comentários que podem ser deixados em uma revisão de código: comentários opcionais e comentários que bloqueiam a aprovação do PR. Comentários opcionais geralmente tratam de alterações que se baseiam em preferências pessoais. Ou seja, eles buscam mostrar uma forma alternativa de implementação do que está no código. Já comentários que bloqueiam a aprovação do diff, geralmente, buscam evitar problemas que a inserção desse commit poderia trazer (ex: identificar casos de canto não prevenidos, implementações que não estão de acordo com a regra de negócio, cenários não cobertos pelos testes etc). Logo, é importante tornar claro para a pessoa autora do PR qual tipo de comentário está sendo deixado, para que ela possa compreender quais alterações devem ser priorizadas. Uma forma de expressar essa diferença é adicionando “nit” aos comentários opcionais (de nitpick, do inglês, que significa esmiuçar).
Porém, vale ressaltar que a definição do que é opcional ou não pode depender do contexto e das prioridades do time. Então, uma forma de padronizar isso entre desenvolvedores e desenvolvedoras do mesmo time pode ser por meio da criação de um documento contendo o que é esperado de uma revisão de código. Dessa forma, autores ou autoras podem compreender o que devem fazer em seu PR para que seja aprovado, e revisores ou revisoras podem saber o que priorizar em sua verificação. Sugestões de tópico desse documento: estruturação de escrita de PR, verificações importantes, regras de padrão de código que devem ser seguidas, erros comuns que devem ser evitados etc.
É, por último, importante citar que em um ambiente de trabalho onde as pessoas se sentem à vontade, seguras de que podem tirar qualquer dúvida que surgir durante as revisões de código, o processo de revisão é mais parecido com uma conversa. Ou seja, torna-se colaborativo e de compartilhamento de informação, enquanto em outros ambientes pode acabar tornando-se mais semelhante à uma prova, na qual a pessoa autora é punida por cometer erros. Portanto, ao realizar uma revisão de código, é essencial fornecer um feedback construtivo, apontando áreas de melhoria de forma respeitosa e sugerindo soluções ou alternativas quando possível.
O processo de revisão de código não é algo definitivo
Finalmente, o processo de revisão de código não é algo definitivo, mas evolui conforme a experiência de cada desenvolvedor ou desenvolvedora, e muda conforme o time no qual se está inserido. É parte do aprendizado e não deve ser temido, mas sim encarado como uma oportunidade de compartilhamento de conhecimento e experiência.
Nossa abordagem não termina aqui, é um convite para uma conversa em constante evolução. Pretendemos continuar compartilhando insights valiosos em próximos artigos, explorando situações práticas e desafios que surgem em nossa rotina. Esperamos que isso também ajude outras pessoas em sua própria evolução no processo de Code Review.
