Boas Práticas Nathan Geeksman

Escrevendo Bons Commits no Git

Escrevendo Bons Commits no Git

Escrevendo Bons Commits no Git

Introdução

A gestão de código fonte é fundamental para garantir a manutenibilidade, escalabilidade e colaboração eficaz em projetos de desenvolvimento de software. No entanto, uma prática muito comum entre os desenvolvedores é o uso inadequado dos commits no Git, resultando em históricos difíceis de entender e que acabam causando mais problemas do que solução.

Nesse contexto, aprender a escrever bons commits é um requisito importante para os profissionais que trabalham com versionamento de código. Esse artigo visa abordar as boas práticas relacionadas à escrita de commits eficazes e claros no Git. Ao final da leitura, você estará apto a identificar melhorias significativas em seu histórico do repositório e contribuir para um ambiente de desenvolvimento mais colaborativo e sustentável.

O que é e por que importa

Commits são uma das principais características do modelo de versionamento Git, representando mudanças feitas no código fonte num momento específico na história de desenvolvimento de um projeto. A escrita de bons commits visa registrar essas alterações de forma clara, concisa e consistente, proporcionando uma visão precisa da evolução do código ao longo do tempo.

Os commits desempenham um papel fundamental em projetos colaborativos, pois permitem que os desenvolvedores, revisores e outros membros da equipe tenham acesso a informações detalhadas sobre as alterações realizadas. Isso facilita:

  • Identificação de problemas: Com commits claros, é possível rapidamente identificar a causa raiz de bugs ou problemas, minimizando o tempo necessário para sua resolução.
  • Revisão e controle de qualidade: Revisores podem analisar os commits para garantir que as alterações atendem aos padrões de código e arquitetura do projeto.
  • Desenvolvimento colaborativo: Com uma estrutura clara nos commits, desenvolvedores podem contribuir mais eficazmente, pois sabem exatamente o que foi feito em cada etapa.

Portanto, a importância dos bons commits reside na sua capacidade de facilitar a manutenção do código, promover a colaboração entre os membros da equipe e melhorar a qualidade geral do projeto.

Como funciona na prática

A escrita de bons commits envolve uma combinação de técnicas e hábitos que, ao longo do tempo, tornam-se parte integrante das rotinas de desenvolvimento. Aqui estão algumas etapas importantes para entender como funcionam os bons commits:

  • Especificar o título: O título deve ser conciso e refletir com precisão as mudanças realizadas no commit. Evite títulos genéricos ou que não descrevam a alteração feita.
  • Exemplo: Adicionado suporte para conexões SSL ao invés de Mudanças
  • Descrever o corpo do commit: O corpo deve fornecer mais detalhes sobre as mudanças realizadas, explicando por que essas alterações foram feitas e como elas impactam o projeto.
  • Exemplo: Alterado a lógica de autenticação para aceitar conexões SSL. Essa alteração é necessária para garantir a segurança das conexões ao servidor.
  • Manter a consistência: Certifique-se de que os commits sejam consistentes em termos de formato, linguagem e estrutura. Isso facilita a leitura e compreensão dos logs do repositório.
  • Revisar e refinar: Antes de finalizar o commit, revise-o para garantir que as informações estão claras e precisas. Considere revisões adicionais para melhorar a descrição ou título se necessário.
  • Usar verbos no presente: É uma boa prática usar verbos no presente para descrever as alterações em vez do passado. Isso ajuda a manter a consistência e facilita a leitura dos logs.
  • Exemplo: Adicionado em vez de Adicionei
  • Manter os commits menores: Tente manter cada commit focado em mudanças relacionadas, evitando grandes commits que podem ser difíceis de revisar e entender.

Exemplo real

Vamos considerar um exemplo de como aplicar as práticas mencionadas anteriormente em um cenário real.

Suponha que você esteja trabalhando em uma aplicação web chamada "Gerenciador de Projetos" e está adicionando suporte para conexões SSL. Aqui está um bloco de código representativo dessa alteração:

// Arquivo: src/main/java/com/gerenciadoprojeto/Config.java

public class Config {
  // Antes da alteração
  // private boolean sslEnabled = false;
  
  // Depois da alteração
  private boolean sslEnabled = true;

  public static String getConnectionString() {
    if (sslEnabled) {
      return "jdbc:postgresql://localhost:5432/gerenciador?sslmode=require";
    } else {
      return "jdbc:postgresql://localhost:5432/gerenciador";
    }
  }
}

Nesse exemplo, podemos ver como a alteração foi realizada para adicionar o suporte para conexões SSL. O código demonstra como o valor sslEnabled foi alterado para true, e como isso impactou na forma como a conexão com o banco de dados é estabelecida.

Ao aplicar as práticas mencionadas anteriormente, poderíamos criar um commit que descreve essa alteração da seguinte forma:

// Commit: Adicionado suporte para conexões SSL

Adicionado suporte para conexões SSL. Essa alteração é necessária para garantir a segurança das conexões ao servidor.

Boas práticas

Manter a consistência

  • Mantenha uma estrutura consistente nos commits, incluindo informações como: data, hora, autor e descrição da alteração.
  • Evite mudanças de formato ou padrão em commit que não sejam necessárias.

Descrever os commits com clareza

  • Use verbos no presente para descrever ações realizadas (por exemplo, "Adicionado" em vez de "foi adicionada").
  • Descreva apenas as alterações feitas, evitando comentários que não sejam relevantes ou necessários.
  • Evite usar expressões genéricas como "Fixou bug", descrevendo com precisão o problema resolvido.

Utilizar verbos no presente

  • Use verbos no presente para descrever ações realizadas, em vez de verbos no passado (por exemplo, "Adicionado" em vez de "foi adicionada").

Armadilhas comuns

Commit muito amplo

  • Evite commits que sejam extremamente grandes e complexos, pois podem ser difíceis de revisar e entender.
  • Em vez disso, divida os commits em menores, mais focados em alterações específicas.

Commit sem descrição

  • Certifique-se de incluir uma descrição nos commits para que outros usuários do repositório possam entender o que foi alterado.
  • Isso também ajuda a manter a consistência e a qualidade dos commits.

Conclusão

A escrita eficaz de commits no Git é fundamental para manter a organização e a clareza do repositório. Ao seguir as boas práticas aqui apresentadas, como manter a consistência na estrutura dos commits e descrever os mesmos com clareza, é possível garantir que outros usuários possam entender facilmente o que foi alterado.

Além disso, evitar armadilhas como commits muito amplos ou sem descrição é crucial para uma comunicação eficaz. Para aprofundar seu conhecimento sobre a gestão de repositórios Git, você pode explorar conceitos relacionados à branching strategy (estratégia de ramificação), merge e pull requests.

Essas habilidades fundamentais ajudam a manter o repositório organizado, facilitando a colaboração em projetos de software.

Referências

  • Martin Fowler. Refactoring: Improving the Design of Existing Code. Disponível em: https://martinfowler.com/books/refactoring.html. Acesso: 2024.
  • SOBRENOME, Git. Documentação Oficial do Git. Disponível em: https://git-scm.com/docs/. Acesso: 2024.
  • Thoughtworks. Clean Code. Disponível em: https://www.thoughtworks.com/insights/blog/clean-code. Acesso: 2024.
  • OWASP. Commit Message Guidelines. Disponível em: https://cheatsheetworld.com/compiling/bash-shell-sh-cheat-sheet.php. Acesso: 2024.
  • SOBRENOME, Git. Documentação Oficial do Git - Commit Message. Disponível em: https://git-scm.com/docs/git-add.html#_commit_message_syntax. Acesso: 2024.