Uma mensagem de commit bem escrita é essencial para a manutenção de um projeto de software colaborativo. Commits mal documentados podem gerar confusão e dificultar o rastreamento das mudanças ao longo do tempo. Neste artigo, vamos explorar as melhores práticas de commit e como escrever mensagens claras e úteis para garantir que seu histórico de versionamento seja fácil de entender e mantenha a organização do código.
1. Por que Mensagens de Commit Claras São Importantes?
Mensagens de commit claras desempenham um papel fundamental na comunicação entre os desenvolvedores. Elas:
- Facilitam a compreensão das mudanças: Um commit bem descrito permite que os colaboradores entendam rapidamente o que foi modificado e o motivo da mudança.
- Ajudam na revisão de código: Code reviewers conseguem analisar mais facilmente as mudanças propostas se as mensagens forem concisas e descritivas.
- Apoiam a depuração: Quando surge um problema no código, uma mensagem clara pode ajudar a rastrear a origem do erro.
- Documentam o histórico do projeto: O histórico do Git serve como uma fonte de documentação do projeto, o que é útil para novos membros da equipe ou para revisitar o código no futuro.
2. Estrutura de uma Mensagem de Commit
Uma boa mensagem de commit geralmente segue um formato simples, composto por três partes:
- Título (header): Uma breve descrição do que foi alterado. Deve ser curta e objetiva (50 caracteres ou menos).
- Corpo (opcional): Explicação mais detalhada das mudanças, se necessário. Aqui você pode fornecer mais contexto sobre o motivo da alteração e suas implicações.
- Rodapé (opcional): Para incluir informações adicionais, como referências a issues ou tickets de bug.
Exemplo de Estrutura:
[Tipo]: Breve descrição da mudança (até 50 caracteres)
Explicação mais detalhada da mudança, se necessário.
- Explicações sobre o problema que foi corrigido
- Detalhes sobre a abordagem adotada
Refs: #NúmeroDaIssue (opcional)3. Tipos de Commits e Convenções de Formatação
Para padronizar as mensagens de commit e torná-las mais compreensíveis, muitas equipes adotam convenções de nomenclatura para os títulos. Alguns dos tipos de commit comuns incluem:
- feat: Adiciona uma nova funcionalidade.
- fix: Corrige um bug.
- docs: Modifica ou adiciona documentação.
- style: Mudanças relacionadas à formatação, como indentação e espaços, que não afetam a funcionalidade do código.
- refactor: Refatoração de código que não adiciona novas funcionalidades nem corrige bugs.
- test: Adição ou modificação de testes.
- chore: Tarefas de manutenção, como atualizações de dependências ou configurações de build.
Exemplo de uso:
feat: Adicionar funcionalidade de login com redes sociais
Esta mudança implementa a possibilidade de login usando Facebook e Google.
Ela também atualiza a biblioteca de autenticação para suportar OAuth 2.0.4. Boas Práticas para Escrever Mensagens de Commit
Aqui estão algumas boas práticas que você pode seguir para escrever mensagens de commit claras e úteis:
a) Seja Breve, Mas Informativo
O título da mensagem de commit deve ser conciso, mas descrever adequadamente o que foi alterado. Evite ser vago. Em vez de “correções feitas”, descreva qual correção foi feita, por exemplo: “fix: corrigir erro de renderização no IE11”.
b) Use o Modo Imperativo
Escreva as mensagens como se estivesse dando uma instrução ao código. Isso torna o histórico de commits mais legível. Exemplos:
- Correto: “Adiciona validação de formulário”
- Errado: “Adicionada validação de formulário” ou “Adicionando validação de formulário”
c) Faça Commits Pequenos e Frequentes
Commits pequenos e frequentes tornam mais fácil identificar a causa de bugs e simplificam o processo de revisão. Cada commit deve corresponder a uma única funcionalidade ou correção de bug.
d) Escreva Mensagens Detalhadas Quando Necessário
Se uma mudança for complexa, utilize o corpo da mensagem para fornecer mais contexto. Explique o porquê da alteração, não apenas o que foi alterado. Isso ajudará revisores e futuros desenvolvedores a entender a motivação por trás da modificação.
e) Referencie Issues ou Tickets
Se seu commit resolver uma issue ou fizer parte de uma tarefa maior, inclua o número da issue ou ticket no rodapé. Isso ajuda a conectar a modificação com o trabalho maior do projeto.
Exemplo:
fix: Corrigir erro de validação do formulário
O formulário estava permitindo o envio de emails em formato incorreto.
Essa mudança garante que apenas emails válidos sejam aceitos.
5. O Que Evitar em Mensagens de Commit
Assim como existem boas práticas, há também erros comuns a serem evitados:
- Não use mensagens vagas: Evite commits como “correções” ou “atualizações”. Isso não fornece contexto suficiente para entender o que foi feito.
- Não combine muitas mudanças em um único commit: Um commit deve focar em uma única alteração ou funcionalidade. Isso facilita o rastreamento de bugs e a reversão de mudanças, se necessário.
- Evite deixar mensagens de commit vazias ou genéricas: Mesmo que a mudança pareça óbvia, escreva uma descrição clara. Isso será útil no futuro.
6. Exemplo de Bons e Maus Commits
Bons Commits:
fix: Corrigir cálculo de frete para clientes internacionais
Corrigido o erro onde o cálculo do frete para fora do Brasil estava ignorando a conversão de moedas.
Maus Commits:
Correções feitasOu:
Trabalho em progresso7. Conclusão
Escrever mensagens de commit claras e úteis é uma habilidade fundamental para o trabalho em equipe e para a manutenção de um histórico de versão saudável. Ao seguir as boas práticas mencionadas, você garante que suas mensagens de commit sejam fáceis de entender, ajudam seus colegas de equipe e melhoram a qualidade geral do projeto.
Lembre-se sempre de manter seus commits pequenos, informativos e escritos no modo imperativo. Essas práticas facilitarão o rastreamento de mudanças e ajudarão a evitar frustrações no futuro.