Boas práticas para revisão de código
Tags: braziliandevs
Published: 2023-10-02 13:54:37

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](#padrao)
- [Empodere-se com ferramentas](#ferramentas)
- [Não aprove por aprovar. Revise com qualidade](#revisao)
- [Dê feedbacks construtivos](#feedback)
 
## 1. Crie um padrão de pull request <a name="padrao"></a>
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:

![Imagem de uma pull request sendo criada](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5id4s1zd4rx2bhoafvjz.png)

### 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 <a name="ferramentas"></a>
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**
![Print da Ferramenta Sonar](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5jzqvkxxa2c6g3tro5dt.png)
No [Sonar](https://www.sonarsource.com/products/sonarcloud/) 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**
![Print da ferramenta Code Climate](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z1acfu1rg3lds45ycavl.png)
No [Code Climate](https://codeclimate.com/) 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**
![Print da ferramenta Sentry](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ch3ir2pih8ontkg3g07z.png)
O [Sentry](https://sentry.io/welcome/) é 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](https://www.jenkins.io/) ou o [Github Actions](https://github.com/features/actions) para criar a automação:
![Print do Github barrando testes](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cvf14woomxc1476a8zq5.png)

### 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:
![Print da ferramenta Vercel](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xm2mb7ipxc6r7u7n2cay.png)
Ferramentas como a [Vercel](https://vercel.com/) 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 <a name="revisao"></a>
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 <a name="feedback"></a>
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:
![Exemplo de sugestão a ser melhorado em uma revisão de PR](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iatzx2oziqv6ffbacbl3.png)
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:
![Exemplo de sugestão em uma revisão de PR](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vlem4nj8831gohal5p13.png)

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:

![Meme sobre revisão de código](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kgufym4qbi6sm2ffxd3u.png)

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!