Documentação e boas práticas são importantes em todo projeto de software, e o Git não é exceção. A documentação clara e a utilização de branchs apropriadas podem ajudar a garantir que o código seja mantido de maneira organizada e eficiente, mesmo em equipes de desenvolvimento de vários membros.

Durante o desenvolvimento de um projeto são feitos inúmeros commits e uma parte importante da documentação são as mensagens que devem ser criadas para organizar cada um deles.

Se você trabalha em alguma empresa ou contribuiu com algum projeto de código aberto, provavelmente seguirá os padrões já definidos por lá, mas qual convenção seguir quando estamos no início da carreira, ainda sem experiência e precisamos desenvolver nossos projetos pessoais?

Como escrever as mensagens?

Há duas maneiras de se escrever uma mensagem de commit: 

Linha de Comando:

Muitas pessoas fazem o commit utilizando somente a primeira linha, que retrata o assunto, mas é possível adicionar mais detalhes inserindo um novo “-m”:

Editor de texto:

Digitando o comando git commit sem uma mensagem ou opção fará com que o seu editor te texto padrão seja aberto para que se escreva uma mensagem de commit.

Com o editor aberto, a primeira linha deverá ser utilizada para inserir o assunto e as demais para inserir a descrição.

Boas práticas para escrever as mensagens:

A escrita da mensagem de um commit é uma parte importante da documentação do Git, pois serve como registro das mudanças feitas no código ao longo do tempo.

É importante escrever mensagens de commit claras e descritivas para que outros desenvolvedores possam entender facilmente o que foi feito e por quê.

Para escrever uma mensagem de commit eficaz, siga as seguintes dicas:

📌 Não pense que seu código é autoexplicativo: Se esforce para escrever uma mensagem que retrate de forma concisa exatamente o que aquela alteração significa.

📌 Especifique o tipo de commit: Utilize prefixos no assunto referente ao tipo de cada commit. Ex:

• feat: uma nova feature (recurso) que você está adicionando a uma aplicação específica ;
• fix: a resolução de um bug;
• style: recurso e atualizações relacionadas à estilização;
• refactor: refatoração de uma seção específica da base de código;
• test: tudo o que for relacionado a testes;
• docs: tudo o que for relacionado à documentação;
• chore: manutenção regular do código. (Você também pode usar emojis para representar os tipos de commit).

📌 Use um verbo no infinitivo: A mensagem do campo “Assunto” (primeira linha) deve iniciar a com um verbo no infinitivo que descreva a ação realizada (Ex: "Adicionar", "Corrigir" ou "Atualizar"), seguido por uma descrição concisa da mudança. Ex: "Adicionar validação de formulário para garantir que todos os campos obrigatórios sejam preenchidos".

📌 Mantenha-a curta e concisa: As mensagens de commit devem ser curtas e diretas, com no máximo 72 caracteres na primeira linha (assunto) e uma linha em branco após a primeira linha (descrição). Isso torna mais fácil para outros desenvolvedores entenderem rapidamente o que foi feito.

📌Forneça contexto: A segunda linha da mensagem deve fornecer um contexto adicional sobre o que foi feito. Por exemplo, se você estiver corrigindo um bug, descreva o problema resolvido.

📌 Mantenha-a clara e objetiva: Mantenha a mensagem clara e objetiva, sem usar jargões ou frases excessivamente técnicas. Isso ajuda a garantir que a mensagem seja compreendida por todos os membros da equipe.

📌 Use passos de ação se necessário: Se o commit requer muitos passos, inclua-os na mensagem de commit, separando-os com uma lista numerada ou com marcadores bullet. Isso ajuda a garantir que o processo seja claro e fácil de seguir.

Em geral, ao escrever uma mensagem de commit, pense na pessoa que estará lendo a mensagem muito tempo depois, quando as circunstâncias poderão ter mudado e a pessoa pode não ter conhecimento do contexto original. Dessa forma, mantenha a mensagem clara, objetiva e forneça o contexto necessário para ajudar outros desenvolvedores a entender rapidamente o que foi feito.

Mantenha essas práticas em mente ao trabalhar com o Git, e você verá que será mais fácil gerenciar e manter o código organizado e eficiente. 😉