Como escrever uma ÓTIMA mensagem de commit no Git

Introdução

A elaboração de mensagens de commit no Git eficazes pode melhorar significativamente a colaboração, a legibilidade do código e a facilidade de manutenção do projeto por muitos anos. No entanto, isso costuma ser negligenciado ou tratado como algo secundário no processo de desenvolvimento. Nesta postagem do blog, vou direto ao ponto e vou apresentar os princípios-chave para escrever mensagens de commit no Git excelentes, que todo desenvolvedor deve seguir!

1. Comece com um verbo no imperativo, com a primeira letra maiúscula, no campo “Assunto”

A mensagem de commit deve indicar claramente o que essa alteração faz. Use um verbo no imperativo com a primeira letra maiúscula no início para facilitar a leitura e a manutenção.

Exemplo

• Adicionar um novo recurso para o login do usuário

• Corrigir corrigir o bug no processamento de pagamentos

• Atualização documentação dos pontos de extremidade da API

2. Mantenha o assunto conciso

Sua mensagem de commit deve ser descritiva o suficiente para transmitir o objetivo do commit, mas concisa o suficiente para ser lida rapidamente. Procure manter o assunto em cerca de 50 caracteres e use o corpo da mensagem para detalhes adicionais.

• Exemplo de boa mensagem de commit: Reestruturar o módulo de autenticação de usuários

• Mensagem de commit incorreta: Reestruturei o módulo de autenticação de usuários para melhorar o desempenho e a legibilidade

3. Separe o resumo do corpo do texto com uma linha em branco

Se a mensagem do seu commit precisar de mais detalhes, adicione um corpo. Certifique-se de inserir uma linha em branco entre o resumo e o corpo para facilitar a leitura.

Adicionar cache local para melhorar o desempenho do aplicativo

Essa alteração implementa um mecanismo de cache local para reduzir a carga no banco de dados
e melhorar os tempos de resposta gerais na rede. O cache é invalidado a cada dez minutos para garantir a atualidade dos dados.

4. Use o modo imperativo

Tendo em mente a convenção padrão, escreva as mensagens de commit no modo imperativo, um modo normalmente associado a ordens e ações. Isso serve para informar o que está sendo feito quando o commit é aplicado.

Exemplos:

• Correto: Adicionar autenticação de usuário

• Incorreto: Adicionada autenticação de usuário

• Correto: Corrigir autenticação do usuário

• Incorreto: Corrigido autenticação de usuário

• Correto: Atualizar autenticação do usuário

• Incorreto: Atualizada autenticação do usuário

5. Explique o “o quê” e o “por quê” no corpo do texto

Use o corpo do commit para fornecer mais detalhes sobre ele: explique o que foi feito e por que foi feito. Isso facilita que outras pessoas — e você mesmo no futuro — entendam o contexto e o motivo da alteração:

• O que: Refatorar a lógica de autenticação

• Por que: Melhorar o desempenho e reduzir a duplicação de código

Exemplo:

Reestruturação da lógica de autenticação

Extraímos a lógica de autenticação de uma classe para um módulo separado, a fim de melhorar o desempenho e reduzir a duplicação de código. Essa mudança
também facilitará a implementação de melhorias futuras.

6. Use marcadores para listas

Se o commit incluir várias alterações, liste-as em pontos. Isso facilita a leitura e a compreensão de cada alteração:

Melhorar o tratamento de erros no processamento de pagamentos

- Adicionar validação aos campos de entrada de pagamento
- Tratar erros da API com um mecanismo de repetição de tentativa
- Registrar mensagens detalhadas de erro para depuração

7. Mencionar questões ou tickets relevantes

Se o seu commit resolver ou estiver relacionado a uma issue ou tarefa específica, mencione-a no seu sistema de gerenciamento de projetos — por exemplo, GitHub Issues, Jira. Isso ajuda a manter o status das issues atualizado, e o contexto será bastante útil para os leitores posteriormente.

Correção do cálculo incorreto do total (#4342)

Corrigimos a lógica de cálculo dos totais dos pedidos, garantindo que
os impostos e descontos sejam aplicados.

8. Analisar e revisar

Antes de fazer o commit e enviar para o repositório, reserve um momento para revisar sua mensagem. Verifique se há erros ortográficos, gramaticais e se a mensagem está clara. Uma mensagem de commit bem escrita reflete profissionalismo e atenção aos detalhes, o que pode economizar tempo e evitar dores de cabeça mais adiante.

Lista de verificação rápida

• Usar letra maiúscula: Você começou a linha de assunto com uma letra maiúscula?

• Conciso: A linha de assunto tem 50 caracteres ou menos?

• Linha em branco: Você inseriu uma linha em branco após o resumo, caso haja um corpo de texto?

• Modo imperativo: A mensagem está no modo imperativo?

• Detalhe: O corpo (se houver) explica o quê, o porquê e o como?

• Listas: Você usou marcadores na sua lista? 

• Referências: Você citou algum issue ou PR relevante?

• Revisão: Você verificou se o texto está claro e se não há erros de digitação?

Conclusão

Escrever boas mensagens de commit no Git melhora a colaboração e a facilidade de manutenção do projeto. Seguindo essas orientações simples — usar verbos imperativos, manter o assunto conciso, explicar o “o quê” e o “por quê” e fazer referência a issues relevantes —, você criará um histórico valioso do projeto, fácil de navegar e entender. Também temos outra postagem intitulada “3 razões pelas quais você deve usar commits convencionais" , caso queira saber mais. 

Também adoraríamos que você se juntasse a nós no Comunidade da Vonage no Slack ou nos enviar uma mensagem no X , e entraremos em contato com você. Mais uma vez, obrigado pela leitura, e nos vemos no próximo post!

Boa sorte com o commit!