Code review: o que é e como fazer?9 min read

Categoria: Engenharia de Softwares

Code review é uma prática poderosa, mas que vem sendo motivo de discussões e críticas por alguns. O fato é que o code review é parte de um fluxo de entrega da engenharia de software que não pode ser ignorado.

Dito isto, nesta postagem vou comentar um pouco sobre a minha experiência com fluxos de revisão de código e vamos falar, também, sobre o que revisar e algumas abordagens que podem ser utilizadas no code review 🙂

Primeiro um resumo do vocabulário utilizado

A ideia é que essa postagem sirva para pessoas de qualquer nível de experiência, portanto, segue um resumo dos termos utilizados nessa postagem e seus respectivos significados:

Jargões/termos
  • Branch – derivação de um ramo do seu código para isolar as modificações do ramo de origem.
  • PR (pull request) – ação utilizada para solicitar a integração de modificações de um branch em outro branch (sendo este último, normalmente, um branch utilizado para deploy).
  • Request changes – é quando você entende que uma modificação deve ser feita em um PR, portanto, você “bloqueia” o merge daquela PR até que você aprove as modificações.
  • Playbook – uma espécie de manual de recomendações e práticas a serem seguidas no projeto. Ele pode guiar o processo de code review (o que deve ser cobrado nas análises de solicitação de pull request)

O que é code review?

Code review

Code review é o processo em que uma pessoa ou mais, que não fizeram parte da implementação, examina um trecho de código. O que isso significa? Significa que a implementação daquele código será avaliada sobre determinados critérios e acordos, que devem fazer justo ao propósito de um processo de code review.

O code review deve ser colaborativo e deve-se evitar que o code review seja o motivo principal para busca de um código perfeito, levando a retenção de PRs por semanas.

Por que fazer code review?

Um dos principais motivos de se ter um processo bem definido de code review é: melhorar o código já existente e garantir que novos códigos estejam aderentes com o nível de qualidade e padrão de código adotado no projeto.

A primeira parte da frase acima – melhorar o código já existente – não é tão complicado de se imaginar: se você tem um código base que não é fácil de ler e dar manutenção e alguém abre um PR com modificações que tornam ele melhor em comparação com o existente, isso por si só já se tornar um motivo para aprovação desta PR (lógico que existem outros pontos a serem avaliado a depender do projeto).

Já a segunda parte da afirmação – garantir que novos códigos estejam aderentes com o nível de qualidade e padrão de código adotado no projeto – se torna um pouco mais complicada, principalmente, se você não tem um playbook com um guia de estilo de código e boas práticas a serem utilizadas.

A ideia de ter um playbook, é justamente, evitar a preferência que cada desenvolvedor pode vir a ter sobre algum aspecto do código, seja estilo, bibliotecas a serem utilizadas e padrões de codificações.

O que avaliar em um code review?

What? Bom código vs um código ruim

O primeiro passo importante sobre essa pergunta é definir os acordos do seu time. O playbook pode ser um caminho. Converse com seu time e entenda o que deve ser avaliado em um PR considerando os aspectos de cada linguagem e um contexto geral (principalmente, se você tiver mais de um time codando naquela linguagem).

Depois que você já tem os aspectos básicos que devem ser avaliados, vem os aspectos de engenharia, que cito alguns:

  • Testes: a funcionalidade tem teste unitário/integração? A cobertura é boa?
  • Nome de variáveis: são claros? Estão de acordo com as boas práticas do clean code?
  • Funcionalidade: conforme a descrição da PR, o código executa o que está descrito?
  • Design: o código está bem projetado? Usa os recursos do paradigma da linguagem?
  • Arquitetura implementada: segue alguma? Está aderente ao que se espera?
  • Bugs e exception: existe alguma que você acredita que pode acontecer?
  • Logs e observabilidade: o código necessita de instrumentação? Foi feita de forma consistente e legível?
  • Dados sensíveis: existe alguma informação sensível sendo adicionado (token, senhas…)?

Lembre-se que o propósito de um processo de revisão de código é ajudar o seu time a melhorar o código e, ao mesmo tempo, evitar bugs. Não é um propósito final do code review (mas sim uma consequência) ter um código perfeito.

Diga qual é sua intenção: use os conventionals comments 🙂

Uma boa prática no momento em que você está comentando uma linha de código é você dizer qual é a intenção daquele comentário: se é uma sugestão, algo que deve ser feito, uma dica ou até mesmo um elogio 🙂

Pensa que você está se comunicando de forma assíncrona e que o texto puro não indica qual é o sentimento daquele comentário. Por vezes você pode estar dando uma orientação que não é um requisito para aquela PR ser aprovada e se você não deixar isso claro, você pode iniciar uma discussão que poderia ser evitada.

By https://conventionalcomments.org – Rotular comentários economiza horas de falta de comunicação e mal-entendidos

Um site que dá uma boa orientação sobre isso é o https://conventionalcomments.org. Na seção de labels (rótulos) ele indica alguns dos prefixos utilizados para começar uma thread:

Comece a thread com um desses rótulos para indicar sua intenção

Então, por exemplo: se você quer indicar que aquela linha de código é uma dica, você começa seu comentário com nitpick: <aqui o seu comentário>.

E se alguém bloquear minha PR (request changes)? O que fazer?

Desapontando: por que não aprovou? WTF?

Nestes casos a melhor forma de resolver um “conflito” entre o revisor e autor do código é conversar pessoalmente (ou no remoto, por chamada de vídeo), caso por texto não estejam chegando a um consenso. Nem sempre todos de um time estarão alinhados sobre o propósito de uma entrega e isso pode gerar conflitos de interesse sobre a qualidade daquele código versus o que de ser entregue.

Recentemente pude perceber isso em um time que precisava entregar MVPs. Por vezes era necessário fazer alguns testes e esses testes não precisavam de uma engenharia complexa, inicialmente, pois aquele MVP poderia ser descartado (lógico que caso não fosse descartado seria necessário refatorar para implementar a feature). O problema é exatamente essa visão do contexto do time, quando o code review é feito de forma cross contexto (por pessoas de fora da squad): se seu projeto não tem o plano bem acordado sobre o como aquilo será feito e o porquê, conflitos em avaliação de PR serão constantes e a melhor forma de resolver é chamando o revisor para explicar o contexto da entrega (se é um MVP, um experimento, POC…).

E se conversar com o revisor não der certo? Neste caso é importante levar isso para os líderes técnicos apoiarem na decisão. É o cenário mais complexo em uma revisão de código, mas por vezes necessário. O que não pode ser feito é deixar um PR sem revisão, por falta de alinhamento.

Conclusão

Vale comentar que o code review é um recurso importante para disseminar conhecimento sobre o negócio, sobre tecnologia/linguagem e engenharia de software, além dos pontos já citados acima. Muito dos questionamento e discussões nas threads de code review podem gerar insights e uma melhor visão sobre todo o projeto para todos.

Não tenha medo do code review e lembre-se: não faça um code review por fazer e também não aprove um PR porque alguém está forçando você aprovar. Se no seu projeto tem revisão de código é porque deve ser feito! Se é só mais uma etapa para burocratizar o processo de merge, então talvez o processo tenha que ser revisto.

Boa parte deste texto foi baseado em minha experiência sobre esse processo, porém deixo algumas referências abaixo que dão uma visão ainda mais abrangente sobre o processo de code review e que vão de encontro com o que escrevi nesta postagem.

Fontes:

Google Engenharia: https://google.github.io/eng-practices/review/
Conventionals Comments: https://conventionalcomments.org/
Por que as revisões de código importam (e realmente poupam tempo!): https://www.atlassian.com/br/agile/software-development/code-reviews

2 comentários em “Code review: o que é e como fazer?9 min read

  1. Caio Morceli disse:

    Boa tarde, Fabio, tudo bem ?

    Eu encontrei no YouTube um vídeo seu abordando algumas questões do MongoDB sobre transações.

    Esse é o vídeo.
    https://www.youtube.com/watch?v=Y7ZbQMCYB7w

    Eu estou estudando uns materiais sobre o MongoDB e achei interessante esse seu material. Gostaria de tirar algumas dúvidas.

    Caso você tenha e possa passar algum contato seu tipo whatsapp para bater um papo rápido sobre isso seria bom para eu te perguntar algumas coisas… Eu estou pesquisando algumas coisas a respeito das garantias do MongoDB quando se trata dos parâmetros write concern, read concern e read preference. São alguns ajustes que o dev. pode fazer no momento de trabalhar com as transações.

    Qualquer coisa deixo meu contato aqui também. (16) 99164****.

    Obrigado. Um abraço.

    1. Oi Caio!

      O ideal mesmo é você mandar suas dúvidas nos comentários da postagem correspondente a sua dúvida: https://criarprogramas.com/2022/04/09/transacoes-com-mongodb-c-e-tech-talk-js/

      Assim, caso mais alguém tenha a mesma dúvida que você, já compartilhamos o conhecimento, aqui no blog.

      Ps: ocultei os últimos 4 dígitos do seu número no seu comentário. Tenha cuidado ao enviar dados sensível em comentário público em blogs 🙂

      Grande abraço!
      Aguardo sua dúvida, aqui!

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *