Mensagens de commit na régua

Sabe aqueles commits bagunçados, sem padrão algum e muitas vezes sem corpo de descrição, contendo apenas o título? Caso não, dê uma olhada nos primeiros commits do meu blog (até 29/03/2021) para entender bem sobre o que eu estou falando.

Realizei os commits iniciais dessa maneira de propósito, para poder ilustrar essa discussão sobre a importância de commits bem estruturados, e como algumas pequenas mudanças de pensamento podem beneficiar o projeto da sua equipe.

🔬 Pesquisa sobre o tema:
Questionei algumas pessoas próximas sobre padrões de mensagens de commit elas costumavam usar em suas empresas e, por exceção de duas, todas as outras respostas diziam que não há um padrão.

Quando falamos sobre a descrição de um commit, falamos sobre facilitar manutenções futuras. Se manutenibilidade é um tópico importante para a sua equipe, você não deveria deixar um commit bem estruturado fora disso.

Acredito também que, pessoas que pouco se importam com um commit bem estruturado, são pessoas que pouco utilizam comandos como git log, git rebase e afins. Mas quando lidamos com um projeto grande, é importante tomarmos nota de que o git também pode servir como ferramenta de documentação, e que um commit bem estruturado pode trazer muitos frutos positivos para toda a equipe.

Duas peças de ouro sobre commits

É comum seguirmos algumas pequenas regras, como a adição de um hash referenciando algum ticket no título, ou até mesmo o padrão Karma para atribuir escopos. As dicas abaixo mudaram completamente meu pensamento sobre como entregar commits bem estruturados:

1. Descreva títulos em modo imperativo

O próprio git possui padrão imperativo de mensagens, tome o uso de git revert ou git merge como exemplos. Recomenda-se então que esse padrão seja mantido, de modo que facilite a leitura do git log também.

Um caminho fácil para seguir essa regra é sempre pensar na seguinte frase antes de determinar um título:

"Ao ser aprovado, esse commit <mensagem do título>"

Exemplos:

• Ao ser aprovado, esse commit atualiza componentes do header
• Ao ser aprovado, esse commit adiciona o componente rodapé

2. Explique o porquê, não o "como"

Assim como bons códigos são auto-explicativos, um bom commit também deve ser. Procure contar histórias sobre o motivo do commit existir ao invés de apenas pontuar aquilo que você fez, por exemplo:

Evite trilhar esse caminho:

Procure fazer dessa maneira:

• feat seguindo o padrão Karma
• (header) é o escopo sobre a área do projeto que está sendo referenciada
• Título apresentado em modo imperativo
• Descrição bem detalhada sobre o motivo do commit existir
• Caso use algum issue tracker, adicione as referências ao final

✨ Detalhes e mais detalhes
Além do Karma, outra especificação bem interessante também é apresentada no Conventional Commits, vale a pena conferir!

Mais boas práticas

Quando se fala sobre commits bem estruturados, é comum encontrarmos também as seguintes regras adicionais:

1. Título sempre em maiúsculo
2. Não coloque ponto final no título
3. Pule uma linha para separar o título da descrição
4. Até 50 caracteres no título
5. Até 72 caracteres por linha na descrição

Que, em conjunto com as duas apresentadas anteriormente, forma as famosas "7 regras para ótimas mensagens de commit".

Caso você esteja em um ambiente sem regras sobre commits, procure levantar toda essa reflexão com a sua equipe de desenvolvimento. Você pode até mesmo se destacar apenas por oferecer uma visão organizacional sobre algo que a maioria ignora.

Valeu demais! 👋🏾