Boas práticas para revisão de código

A revisão de código é uma atividade de extrema importância no processo de qualidade de código. Ultimamente tenho atuado como tech manager revisadora de pull request. Então quero compartilhar algumas boas práticas que aprendi tanto revisando quanto enviando um código para revisão. Me diz o que tem feito por aí também? :)

Índice

• Crie um padrão de pull request
• Empodere-se com ferramentas
• Não aprove por aprovar. Revise com qualidade
• Dê feedbacks construtivos

1. Crie um padrão de pull request

Para facilitar a vida, é importante definir um padrão de como a pessoa desenvolvedora irá criar a Pull Request, senão você pode acabar recebendo tanto super descrições com detalhes e imagens, quanto um "Alteração realizada. Valeu, tamo junto".

Como configurar

Para fazer isso, basta criar no seu projeto uma pasta chamada .github e dentro dela criar um arquivo pull_request_template.md.

Ps: caso você queira fazer isso uma única vez, para deixar o template válido para toda a organização, basta criar um repositório com o nome .github e o arquivo pull_request_template.md.

No arquivo pull_request_template você escreve o modelo que espera receber, então sempre que alguém abrir uma PR, aparecerá o modelo para preencher:

O que adicionar em um template

Pode parecer um trabalho a mais para fazer além da task, mas facilita demais a vida de quem vai revisar, para entender o contexto da sua alteração e revisar de maneira mais rápida.

Algumas sugestões do que adicionar em um template:

• Qual o tipo dessa PR?
• Descrição das mudanças feitas
• Adicionar imagens ou GIFs do resultado
• Origem da alteração: ticket, conversa no slack, task no jira? Deixa o link!
• Testes realizados
• Documentação
• Ações para realizar após a aprovação: como executar uma query no banco, realizar alguma configuração ou algo do gênero
• Deixar claro quais campos são obrigatórios e quais são opcionais

Exemplos de template

Para definir o modelo, o melhor é alinhar com o time e chegar a um acordo que faça sentido para todos. Mas vou deixar aqui alguns modelos que já testei:

Simples e direto:

## Descrição breve da PR: (obrigatório)

## Exemplos de como testar a PR: (obrigatório)

## Imagens anexas: (opcional)

Mais detalhado:

## Tipo de alteração: 
[ ] Nova funcionalidade
[ ] Correção de bug
[ ] Teste
[ ] CI/CD
[ ] Documentação

## Motivo da alteração:

## Origem da solicitação:

## A alteração foi testada?

## Evidência de teste realizado:

De acordo com o objetivo do seu projeto e maturidade do time, pode ser que alguns informações a mais sejam necessárias ou não. Além de que é algo que pode ser testado e ajustado de acordo com a experiência do time com o modelo definido.

2. Empodere-se com ferramentas

Para adiantar o trabalho, utilizar ferramentas é super útil e você pode integrar elas no seu git. Assim elas vão trabalhar sempre que uma PR for aberta.

Qualidade

Existem ferramentas que fazem a varredura no código e já analisam pontos como code smell, vulnerabilidade e bugs.

Sonar

No Sonar você pode definir regras de qual o valor máximo permitido em cada categoria de qualidade. Caso a alteração ultrapasse essas definições, ela já nem fica disponível para mergear ao código.

Ele também pode ser integrado no VS Code para que alerte durante o desenvolvimento.

Code Climate

No Code Climate também existem métricas parecidas e ele te dá uma nota de avaliação da qualidade do seu projeto. Na PR ele acrescenta sugestões de alteração.

Sentry

O Sentry é uma ferramenta focada na detecção de erros e tem evoluído para já avisar na PR caso ela tenha gerado algum incidente em produção. Como nesse exemplo que aprovei uma PR mas ao chegar em produção o Sentry suspeitou que ela impactou uma funcionalidade.

Testes

Quando você tem sua cobertura de testes integradas no CI/CD, é válido deixar isso visível na PR. Ferramentas como o Sonar já conseguem integrar diretamente ou você pode utilizar ferramentas como Jenkins ou o Github Actions para criar a automação:

Preview

Facilita bastante ter um link de preview para testar a alteração realizada. Seja para ver uma melhoria visual ou para testar mudanças importantes no fluxo do backend:

Ferramentas como a Vercel já disponibilizam automaticamente na PR um link de um ambiente de homologação para pré visualizar a alteração, mas essa automação também pode ser realizada com o seu processo de CI/CD.

3. Não aprove por aprovar. Revise com qualidade

Ok, o que eu reviso em um código então? Deixo aqui algumas sugestões:

• Deixou algum comentário ou console.log sem querer?
• Erros de sintaxe
• Erro ortográfico (Erro de português para o cliente nãoo)
• Manteve o padrão de código?
• A alteração está fazendo o que diz a descrição?
• A alteração resolveu a problemática que se propôs?
• A alteração não está impactando de maneira equivocada outro processo que funcionava?

Essa é minha lista de verificação atual. E claro, quanto mais avançado e estruturado o padrão de qualidade do seu time, menos você tem que se preocupar em revisar coisas mais básicas como sintaxe e cada vez mais você vai poder focar se a solução é válida para a regra de negócio.

Em projetos menores e com equipes iniciantes, é comum fazer verificações mais rápidas e com pouca/sem automação. Mas quanto mais a equipe cresce e o projeto escala, o nível de revisão tende a ser mais rigoroso.

4. Dê feedbacks construtivos

O processo de revisão é um passo importante para manter o código legível e funcional, então é essencial que ambas as partes se tratem de maneira educada e sempre com feedbacks construtivos. Não é nada pessoal, apenas focado em manter a qualidade na escrita do projeto.

Considerações

Ao localizar um erro, é uma boa prática deixar uma sugestão de mudança aplicada no código, se possível. Caso o trecho de código seja muito grande, você pode deixar um comentário explicativo com sugestões e sua visão de por onde a alteração deve se encaminhar.

Em caso de dúvidas sobre a alteração em uma funcionalidade, impactos ou mudança de processo, é importante já perguntar durante a revisão.

Não se apegue a solução que você imaginou desenvolver. Se o código revisado atende todos os critérios necessários, não há necessidade de solicitar alteração para a exata maneira que você pensou.

Exemplos

Exemplo de revisão minha que poderia ter sido melhor:

Apesar de ter sido direta, nesse caso eu poderia já ter apontado quais partes da frase estavam incorretas e deixar uma sugestão de alteração. Isso evitaria um alinhamento extra no slack e mais um commit extra com o ajuste final. O que pode parecer pouco, mas com muitas PRs para revisar, no final do dia isso demanda um bom tempo dedicado.

Nesse segundo exemplo já deixei uma sugestão de alteração e o motivo que achava válido:

Como revisor não somos donos da verdade, então é importante em casos de dúvida alinhar com a pessoa o que ela levou em consideração para chegar naquela solução. E claro, sempre coletar feedback e evoluir nesse processo.

Conclusão

O processo de revisão envolve várias vertentes de um projeto e é importante ter conhecimento não só técnico como também da regra de negócio.

Boas práticas podem ser implementadas desde times pequenos, para criar uma cultura de revisão e troca de conhecimento entre as pessoas.

Ferramentas podem ajudar a agilizar nosso trabalho e detectar detalhes que podem passar despercebidos, mas não substituem totalmente a revisão humana, que é de extrema importância para garantir um produto funcional e de acordo com a realidade dos clientes.

E finalizado com uma imagem de como medir a qualidade do seu código:

Deixa um feedback se utiliza alguma dessas técnicas no seu dia a dia ou se tem mais alguma boa prática que eu deveria aplicar!