Como fazer uma boa revisão de código

Publicado por Murillo Flores no dia dev

Se eu pudesse dar só uma dica sobre o futuro seria esta: Use TDD. Mas se eu pudesse dar duas dicas, seriam estas: Use TDD e pratique a revisão de código junto com o seu time. Mostre o seu código para algum outro desenvolvedor antes de colocá-lo no perigoso mundo real do ambiente de produção e ajude seus colegas revendo os códigos deles antes de irem pro ar. Revisar código ajuda a encontrar aquelas pequenas arestas não aparadas e a disseminar conhecimento sobre a base de código. Fazer uma boa revisão é difícil e gera dúvida em muitos desenvolvedores, principalmente aqueles que estão começando agora. Resolvi escrever este post para compartilhar um pouco mais da minha experiência nessa prática.

Cada vez mais comum entre as equipes de desenvolvimento de software, a revisão exige desapego e benevolência. Desapego de quem escreveu para colocar “o código a tapa” e estar aberto para as sugestões que naturalmente virão, e benevolência de quem revisa que tem de estar disposto a dedicar parte de seu tempo para melhorar a entrega alheia e aprender um pouco mais sobre trechos de código que não lhe dizem respeito no momento. Adquiridas essas duas qualidades, os benefícios de revisar e ter seu código revisado são grandes: disseminação de conhecimento entre os pares, aumento da responsabilidade e do collective ownership entre o time e aumento da qualidade geral do código.

Quando eu comecei a fazer revisões de código, eu não tinha muita ideia do que estava fazendo, nem de como fazer isso. Eu realmente não sabia o que considerar e o que não considerar, ou como escrever as minhas considerações e comentários a respeito do código revisado. Com o passar do tempo, desenvolvi uma técnica para fazer as revisões, e acho que já posso compartilhar algumas dicas. Essas dicas são baseadas na minha própria experiência e no que aprendi com os meus colegas conversando sobre o tema.

Pois bem aí vão elas:

1. Entenda a razão da modificação

A primeira coisa a se fazer para uma revisão de qualidade é entender por que esta modificação foi necessária. A pergunta chave é: Qual problema está sendo resolvido? Se o seu time usa Pull Requests no github como plataforma para a revisão, procure na descrição do Pull Request a resposta para essa pergunta e se não a encontrar, aí está o seu primeiro feedback para o autor.

Se o problema resolvido estiver relacionado a um bug, procure entender quais os sintomas deste bug, em que cenários ele ocorria e como pode ser reproduzido. Se for a adição de uma nova funcionalidade ao sistema, leia a sua definição e saiba como ela interage com as demais. Tudo isso vai ser muito importante durante a revisão.

Só siga em frente quando você tiver certeza de qual é o motivo e qual a intenção dessa alteração.

2. Liste alguns cenários nos quais o código deve funcionar

Agora que você já sabe que problema está sendo resolvido com essa alteração, é importante listar uma série de cenários sob os quais o código dessa alteração será submetido e como o sistema deverá se comportar nesses casos.

Se o autor das modificações for um cara legal, ele provavelmente terá listado alguns cenários para você. Aceite essas sugestões e pense se existe algum outro caso de uso que ele não especificou. Achar um cenário não imaginado pelo autor é provavelmente uma das melhores contribuições que você pode fazer - isso pode quebrar algumas das suposições feitas por ele e alterar bastante a solução.

A dica aqui é usar toda a sua experiência como desenvolvedor e se perguntar coisas como: E se essa requisição falhar? E se o serviço estiver fora do ar? E se o disco estiver cheio?

3. Comece pelos testes

Você já sabe qual problema tem de estar resolvido e sob que condições. Nada mais natural que os testes feitos pelo autor das modificações garantirem exatamente isso, portanto comece a sua revisão lendo estes testes.

Leia os testes com atenção redobrada e entenda - realmente entenda - se eles garantem a solução do problema sob todos os cenários listados. Esses testes são a garantia futura de que esse problema não vai reviver das cinzas, então eles devem ser completos e claros.

Os testes devem ser corrigidos com prioridade, portanto, se encontrar algum ponto a ser melhorado, já mande logo suas sugestões para o autor.

Por fim, nunca é demais executar esses testes em seu computador, apenas como garantia.

4. Revise o código

Você já tem um problema claro, cenários bem descritos e testes que garantem que tudo funciona como deveria. Uau, esse código sob revisão já é bem promissor! É chegado o grande momento de descobrir como seu colega resolveu o problema.

A dica aqui é revisar o código das camadas mais externas do sistema para as mais internas, lendo função por função, um nível de abstração de cada vez. Ao ler cada função, você deve sempre estar se perguntando:

  • Esse código faz sentido?
  • Funciona em todos os cenários em que deveria?
  • Está no lugar certo?
  • Existe um jeito melhor (mais fácil, mais correto, mais legível) de fazer isso?
  • Vai funcionar com X milhares de requests por minuto?
  • Vai funcionar se o serviço/sistema Y estiver fora do ar?
  • Segue as convenções de código do time?

Se você já leu o Clean Code são grandes as chances que essas perguntas surjam naturalmente na sua cabeça sempre que você está lendo código. Se você não leu, eu te adianto que uma das mais valiosas dicas do livro é nos mostrar que a única medida de qualidade de código válida é: WTF’s/minuto.

Sempre que você estiver revisando e a inconfundível pergunta “Que P*#$% é essa?” surgir na sua cabeça, aí pode estar uma boa oportunidade de melhoria. Reflita sobre o que fez você se perguntar isso e então deixe seu comentário/sugestão para o autor.

Wtfs/minute

5. Teste a funcionalidade como um usuário e, depois, como um idiota

Problema, Cenários, Testes e Código: Tudo entendido e revisado. Seu colega é um grande programador e tudo faz sentido e funciona. É hora de liberar logo esse código para produção e voltar para as suas atividades, certo? Errado. É hora de esquecer o código, esquecer a tecnologia e pensar como um usuário. É hora de usar o seu software.

Uma vez que você é um programador não existe disciplina ou fórmula mágica que te converterão novamente em um simples usuário de computador, mas todas aquelas horas jogando RPG devem ter te ensinado a desempenhar um papel de vez em quando. Portanto use essa capacidade e haja como um usuário, pense como um usuário, tente resolver as coisas do jeito que só um usuário tentaria. Lembre do problema sendo resolvido, lembre dos cenários e sinta que você tem esse problema e está em um desses cenários. E agora use o software com as modificações novas e brilhantes feitas pelo seu colega para resolver esse problema. Conseguiu? Ótimo, agora tente de novo em um cenário diferente. Repita isso até que você tenha absoluta certeza que os seus usuários conseguirão resolver o problema usando seu software, e estarão contentes por isso e não xingando no final do processo.

É importante lembrar que o usuário é uma pessoa bem intencionada, competente e que tem o propósito real de resolver problemas com o seu software. Nunca subestime ou julgue seus usuários, de verdade.

Por outro lado, é igualmente importante que a sua solução seja a prova de idiotas, simplesmente porque sistemas a prova de idiotas são mais seguros para os usuários. Portanto agora é a hora de testar o software como um idiota. É hora de resolver problemas como um idiota. Clique no lugar errado, cole um texto muito longo, clique três vezes seguidas muito rapidamente. Se o software e o código do seu colega resistirem a isso, vocês realmente sabem o que estão fazendo. Se algo sair errado, anote seu comentário e ajude seu colega a se tornar um programador ainda melhor.

6. Repita para você mesmo que tudo isso faz sentido

O código está bom e os usuários vão conseguir usar e resolver os seus problemas. Isso é excelente e a sua revisão está quase finalizada. A cereja do bolo é repassar mentalmente, ou talvez contar para um urso de pelúcia, toda a linha de raciocínio que você seguiu para essa revisão de código. Você deve dizer, em voz alta, algo como:

“Bom, o problema que essas alterações resolvem é tal, e isso foi solucionado fazendo isso, aquilo e aquilo outro. Isso funciona porque em tal situação tal coisa vai acontecer. E não quebra porque o autor adicionou aquela validação, lá na classe tal.”

Fazer isso, principalmente em voz alta, é importante porque te ajuda a encontrar falhas na sua linha de raciocínio que você talvez não tenha percebido enquanto estava focado na tarefa de revisão. Talvez nesse momento você se lembre de um cenário que esqueceu. Talvez lembre-se que existe um jeito melhor de garantir que a aplicação não quebra em uma determinada situação. Ou talvez você simplesmente conclua que tudo que disse faz sentido, e que esse código está bom o suficiente para enfrentar o ambiente de produção.

7. Deixe um comentário final

Agora que você já terminou sua revisão, e escreveu as suas considerações para o seu colega autor das modificações, é hora de deixar seu comentário final.

Se o código já está bom o suficiente para ir pro ar e você não tem mais nada a dizer, é comum escrever coisas como LGTM, ou Ship it!, como fazemos aqui na Resultados Digitais. Se as considerações que você deixou são sobre coisas que você considera pequenas e não críticas, você pode dizer pro seu colega ficar a vontade para colocar no ar depois de ler seus comentários. Agora, se você vai querer revisar novamente depois que o seu colega ler seus comentários e decidir o que fazer a respeito, deixe isto bem claro no seu comentário final.

O importante em um comentário final é deixar claro para o seu colega qual foi a sua avaliação geral das modificações e com que sentimento você terminou a revisão.

Neste último recado, como em todos os demais, seja cortês e mantenha um tom positivo e sugestivo (e não impositivo). Isso ajuda o autor a aceitar e entender melhor as suas sugestões e dúvidas. Você pode escrever comentários como “O que acha de fazermos isso?” e “Ficaria melhor se fizessemos assim?” ao invés de “Modifique isso” ou “Faça desse jeito”.

Comentário final

*

Se alguém tivesse me mostrado essas dicas antes da minha primeira revisão de código, tenho certeza de que ela teria sido muito melhor, satisfatória e mais relevante para o meu colega autor do código. Mas aqui, como em tudo, vale a máxima de que a prática melhora o desempenho. Com o passar do tempo, com mais e mais códigos revisados, tenho certeza de que me tornei um programador melhor e pude ajudar os meus colegas a se tornarem também. E, afinal de contas, não é pra isso que estamos no mesmo time?

Espero que essas dicas sejam úteis pra você também ;)

Há um tempo atrás o Jônatas Paganini, colega aqui na RD, fez uma apresentação no Floripa On Rails sobre o tema. Se você também tiver uma, compartilhe com a gente. Você já faz revisão de código junto com seus colegas? Ainda não mas quer começar? Tem uma técnica diferente, outras dicas? Nos conte um pouco mais nos comentários.

Murillo Flores

Murillo Flores

Full Stack Developer

Comentários