6 Coisas que você precisa saber ao escrever commits

Édipo Hikari — Tue, 05 Nov 2024 08:48:04 +0000

Introdução

No desenvolvimento de software, a forma como documentamos nossas alterações no código é tão importante quanto o próprio código. Mensagens de commit bem escritas são fundamentais para manter um histórico claro e compreensível do projeto, facilitando a colaboração entre desenvolvedores e a manutenção futura do código.

Como Peter Hutterer, desenvolvedor Linux, sabiamente disse: "Um bom commit mostra se um desenvolvedor é um bom colaborador".

Por que se preocupar com mensagens de commit?

As mensagens de commit são mais do que simples anotações - são documentos históricos que contam a evolução do seu projeto. Um commit bem escrito:

Facilita a compreensão das mudanças realizadas
Auxilia na identificação de bugs
Melhora a colaboração entre membros da equipe
Serve como documentação para futuras referências
Automatiza processos de release e changelog

Conventional Commits

O Conventional Commits é uma especificação para adicionar significado semântico às mensagens de commit. Seguindo esta convenção, suas mensagens de commit devem seguir a estrutura:

<tipo>[escopo opcional]: <descrição>

[corpo opcional]

[rodapé opcional]

Tipos principais:

feat: - nova funcionalidade
fix: - correção de bug
docs: - alterações na documentação
style: - formatação, ponto e vírgula faltando, etc
refactor: - refatoração de código
test: - adição ou correção de testes
chore: - atualizações de tarefas de build, configurações, etc

Exemplo:

feat(login): adicionar autenticação com Google

Implementa o botão de login social usando OAuth2 do Google
para facilitar o acesso dos usuários.

Closes #123

Erros Comuns a Evitar

1. Usar o Git como Sistema de Backup

Evite mensagens como:

"salvando trabalho"
"fim do dia"
"wip"
"alterações diversas"

2. Commits Desorganizados

Mantenha alterações relacionadas juntas. Por exemplo, ao trabalhar em uma feature que afeta múltiplos arquivos, faça um único commit que englobe todas as alterações relacionadas.

Branches Privadas

Crie branches privadas para commits temporários usando o padrão:

private/seu-nome/feature-em-desenvolvimento

Isso permite commits intermediários sem poluir o histórico principal do projeto.

As 6 Regras de Ouro

1. Limite o Título

Máximo de 50 caracteres
Seja conciso e direto

2. Separe Título e Corpo

Use uma linha em branco entre o título e o corpo do commit
Melhora a legibilidade

3. Limite as Linhas do Corpo

Mantenha as linhas do corpo com máximo 72 caracteres
Facilita a leitura em diferentes interfaces

4. Use o Modo Imperativo

Escreva como se completasse a frase "Este commit vai..."
Exemplo: "Adicionar função de busca" em vez de "Adicionada função de busca"

5. Explique o "O quê" e o "Por quê"

Foque no que foi alterado e por qual motivo
Deixe o "como" para o próprio código

6. Referencie Issues

Vincule commits a issues quando relevante
Use palavras-chave como "Fixes", "Closes", "Resolves"

Exemplo Prático

feat(carrinho): implementar cálculo automático de frete

- Adiciona integração com API dos Correios
- Implementa cache de 15 minutos para consultas
- Adiciona validação de CEP

Resolve o problema de cálculo manual de frete que causava
erros frequentes no checkout.

Closes #456

Conclusão

Mensagens de commit bem escritas são um investimento no futuro do seu projeto. A adoção do Conventional Commits junto com as boas práticas apresentadas torna o desenvolvimento mais profissional e eficiente. Lembre-se: cada commit conta uma história - faça com que essa história seja clara e útil para todos.

DEV Community: Édipo Hikari