A anatomia do pull request perfeito

4 melhorias de code review que farão seu time voar 🚀

by Glenn Carstens-Peters on Unsplash

As características de um bom pull request vão muito além do que apenas o diff do código. A qualidade do código é apenas um dos fatores que precisamos levar em conta ao criar um PR.

PRs grandes geram um grande overhead no processo de review do código, facilitando a introdução de bugs.

Por este motivo, a otimização deste processo deve fazer parte do core de qualquer equipe ágil quando o assunto é desenvolvimento de software.

A velocidade de desenvolvimento do produto está diretamente relacionada à qualidade dos PRs submetidos ao repositório.

Porque você deve se preocupar com isso

• Um bom pull request é revisado rápidamente;
• Diminui a introdução de bugs na base de código;
• Facilita o onboarding dos desenvolvedores que estão entrando no time.
• Agiliza o processo de review e consequentemente o merge.

Com isso em mente, vamos detalhar os pontos que precisam de mais atenção ao criar um PR.

O tamanho do pull request

O primeiro passo para identificar PRs problemáticos é observar a quantidade de linhas que ele altera na base de código.

Existem diversos estudos mostrando que quanto maior o PR, menores são as chances identificar bugs no code review.

Classic, right? 😂

Além disso, PRs grandes bloqueiam outros desenvolvedores que podem estar dependendo deste código.

Não seria eficiente definir um número máximo de linhas para um PR, porque cada equipe tem uma velocidade, mas o ideal é que o code review de um PR não leve mais do que 1h para ser feito.

Estudo feito pelo site small business programming

Tendo este número em mente, o tamanho máximo sugerido para um PR é de 500 linhas de código — Contanto adição e remoção de linhas

Como podemos observar no gráfico acima, PRs com mais de 500 linhas tendem a levar mais de 1h no Code Review, o que diminui as chances do reviewer de encontrar bugs, atrasa o desenvolvimento do produto e bloqueia outros desenvolvedores.

O princípio de responsabilidade única (SRP)

Fonte: https://www.toptal.com/software/single-responsibility-principle

Outro ponto a se observar para criar um PR foda é seguir o conceito de SRP (Single responsibility principle)

The single responsibility principle is a computer programming principle that states that every module or class should have responsibility over a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class.

Assim como classes e modulos, PRs devem fazer apenas uma coisa.

Isso diminui drasticamente o overhead causado ao revisar um código que tenta resolver vários problemas.

Antes de submeter um PR para review, tente aplicar o principio de responsabilidade única. Caso este código esteja fazendo mais de uma coisa, quebre em outros Pull Requests.

Exemplos de PRs que tem apenas uma função:

• Adicionar um atributo X no modelo Y
• Adiciona o método create no controller X
• Adiciona o componente Y no ReactJS
• Migra os dados da coluna Y para a coluna X
• Adiciona o plugin X
• Atualiza a gem Y
• Corrige o problema X na classe Y

O titulo e a descrição são importantes

Ao criar o titulo e a descrição do PR, considere que o reviewer está chegando hoje no seu time, e que este, não sabe o que se passa no resto do código.

É necessário que o PR explique o que efetivamente está sendo alterado.

Sempre que possível utilize imagens (screenshots) para demonstrar o que mudou — 2 screenshots com antes e depois são suficientes.

Exemplo de um PR bem descrito

O titulo do PR deve ser autoexplicativo

O titulo deve ser suficiente para que qualquer dev consiga entender o que está sendo alterado.

Alguns exemplos:

• Add test case for getEventTarget
• Improve cryptic error message when creating a component starting with a lowercase letter

Faça uma descrição útil

• Explique porquê este PR está sendo criado.
• Deixe claro como ele faz o que está se propondo fazer. Por exemplo: Ele altera uma coluna no banco? Como isso está sendo feito? O que acontece com os dados antigos?
• Liste o quê foi foi alterado no PR. Bullet points são excelentes para criar changelogs.

Recapitulando

Tamanho do PR

Deve ser pequeno. O PR deve ter no máximo 500 linhas — somando as linhas adicionadas e removidas — ou deve ser pequeno o suficiente para revisado em até 1h.

PS: Se quiser aumentar ainda mais a qualidade dos pull requests e reduzir o tempo de review, faça um experimento diminuindo este número para 300 linhas.

Single Responsibility Principle

O pull request deve fazer apenas 1 coisa;

Titulo do PR

Faça um titulo autoexplicativo descrevendo o quê o PR faz.

Descrição do PR

Detalhamento com o quê foi alterado, porquê foi alterado e como foi alterado. Caso necessário, adicione screenshots.

Dúvidas? Sugestões? Deixe abaixo nos comentários!