DEV Community

Cover image for Boas práticas para revisão de código
Lorena GM
Lorena GM

Posted on

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

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:

Imagem de uma pull request sendo criada

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)
Enter fullscreen mode Exit fullscreen mode

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:
Enter fullscreen mode Exit fullscreen mode

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
Print da Ferramenta 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
Print da ferramenta 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
Print da ferramenta 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:
Print do Github barrando testes

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
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:
Exemplo de sugestão a ser melhorado em uma revisão de PR
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

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

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!

Top comments (10)

Collapse
 
mateusmoov profile image
Moov

Todas as ferramentas não fazia ideia que existiam, parecem muito boas! A questão do texto padrão quando a pessoa abrir o PR já era uma coisa que eu tinha curiosidade de como funcionava mas nunca corri atrás pra ver.

Ótimo artigo!

Collapse
 
lorenalgm profile image
Lorena GM

Valeu, Mateus!

E simm, ter um texto padrão já ajuda demais pro dev ter uma noção, principalmente quem tá chegando na empresa que pode ficar meio perdido de como o time prefere receber

Collapse
 
nandosts profile image
Fernando Melo

Eu costumava gostar muito de usar o gitmoji nas PR antigamente kk, fica tão bonitinho, e ajuda em algum nivel o entendimento das PRs

Mas sim, a importância desse post é gigante!!! Parabéns prima, muito bom e com certeza eu vou ler ele muitas vezes ainda kk

Collapse
 
lorenalgm profile image
Lorena GM

Valeu demais, primo!
Mds gitmoji fica bonitão o commit kkk Bem lembrado, tinham me recomendado mas não cheguei a usar. Vou testar!

Collapse
 
antoniorws profile image
Antonio Serra

Ótimo artigo!

Collapse
 
cherryramatis profile image
Cherry Ramatis

apesar de usar algumas tecnicas para review e boas praticas de pull request, é muito esclarecedor ver a visão de uma lider que faz isso no dia a dia! aprendi varias coisas pra ir mandar no meu time 👀

Collapse
 
nettobruno profile image
Bruno Netto

Excelente artigo, Lorena.

Eu sempre trabalhei sozinho, e agora que estou em uma equipe estou pegando o esquema de revisar e pedir revisão dos meus colegas.

O seu artigo ajudou de mais a esclarecer o que fazer, e o que não fazer nas revisões. Parabéns, e obrigado pelo conteúdo.

Collapse
 
mels profile image
Melina Schneider

adorei! sempre tive medo de PR ahahha mas esse artigo ajudou mt

Collapse
 
lumamontes profile image
Luma Montes

muito top o artigo, Loki!! as tuas revisões de PR sempre são as melhores, vários pitacos construtivos hihi

Collapse
 
wesllycode profile image
wesllycode

Muito bom !