22

Existem práticas recomendadas para realizar commits e escrever comentários nesses commits, para uma melhor comunicação e entendimento durante o processo de desenvolvimento de software?

6
  • Ai varia, se existe algum tutorial, ou livro padronizando a atividade, e alguem souber, acredito que nao. Agora se nao houver, as responsatas serao dadas como sugestoes, assim como ocorrem com outras que nao tem uma solucao definitiva, ou exata. Se for assim, qualquer resposta para um provlema que possa ter mais de uma alternativa de resolucao serão tambem baseadas em opniao, e portanto invalidadas. Fui claro?! :D 30/04/2015 às 17:01
  • 1
    Provavelmente será fechado esse tópico mas vou expressar minha opnião. Se você esta referindo commit ao ato de executar o comando git commit -m "meu comentario". Primeiro você deve enteder o significado de commit, Commit é fazer permanentes um conjunto de mudanças e também um ato de enviar. Ou seja não acredito que exista a melhor pratica e o significado da palavra fica fácil, ao dar o commit no git você deve comentar quais mudanças no determinado documento ocorreu.
    – Skywalker
    30/04/2015 às 20:17
  • Ou o camarada quando realiza alguma alteração so coloca: git commit -m "Mechi em alguma coisa ae e tela voltou a abrir, qualquer duvida fala comigo!" 30/04/2015 às 21:44
  • Ele perguntou sobre comentários, não da quantidade de tarefa por commit. A propósito, aqui tem uma pergunta sobre a quantidade de informação por commit.
    – Math
    5/05/2015 às 12:29
  • 1
    Esclarecendo: A cada commit seria a descrição referente à tarefa que foi dado commit. 5/05/2015 às 13:57

2 Respostas 2

21

Granularidade dos commits

Como já respondi aqui, a principal boa prática é tentar comitar uma funcionalidade por vez, independente se alterou um ou 10 arquivos. Dessa forma seria possível reverter uma mudança em caso de problemas, o que não é tão raro quanto se pensa.

Note que alteração em muitos arquivos ao mesmo tempo é sintoma de que poderia dividir a alteração em partes.

Comentários

Não sou a favor de grandes explicações em comentários de commits.

O que recomendo é uma explicação em alto nível de no máximo uma linha do que foi feito, como uma nota mental, a partir da qual o desenvolvedor possa lembrar-se ou pelo menos procurar a especificação daquela mudança.

Conteúdo do comentário

Algo usado em praticamente todas as empresas que levam o processo a sério, seja ele ágil ou tradicional, é vincular cada commit a um ticket ou issue de algum sistema como o Jira, Mantis ou Bugzilla.

Cada ticket é, por sua vez, vinculado a uma tarefa específica ou a toda uma estória de usuário, dependendo também da granularidade em que o projeto está planejado.

Assim, o desenvolvedor pode facilmente consultar a documentação e possível discussão sobre o bug ou funcionalidade. Também é possível rastrear no sistema de gerenciamento de versões quais foram as alterações necessárias para implementar a funcionalidade X.

Auxílio de ferramentas

A maioria das IDEs possui integração com as ferramentas de tickets e, configuradas corretamente, são capazes de adicionar automaticamente ao comentário do commit o número do ticket em que o desenvolvedor está trabalhando.

Também é possível configurar uma regra no sistema de versionamento para impedir que commits sejam feitos sem comentários e sem vínculo com algum ticket cadastrado.

Em geral não recomendo tal nível de controle, mas é algo comum em grandes empresas para evitar que desenvolvedores inexperientes façam commits indevidos.

4
  • 2
    Obrigado!! E obrigado pela Resposta!! 5/05/2015 às 15:30
  • 1
    @TiagoAmaral De nada! Só uma coisa, vi que você aceitou minha resposta como certa muito rapidamente, mas considere também a do Gabe. Minha resposta foi geral, baseada na vivência em empresas, a do Gabe é mais focada no Git e na documentação oficial.
    – utluiz
    5/05/2015 às 16:04
  • Sim vou dar uma olhada. Aceitei pois não acreditava que poderiam surgir mais respostas, devido a um certo grau de rejeição de outros usuários. 5/05/2015 às 16:10
  • 1
    @TiagoAmaral Não dê muita importância às desavenças e discórdia em torno de uma pergunta. O site ainda é novo, e muita coisa continua sendo discutida. Sempre tem gente disposta a ajudar. E o mesmo vale se você quiser responder uma pergunta... Se achar que consegue ajudar alguém, melhor fazê-lo do que ficar debatendo se a dúvida tem mérito.
    – Gabe
    5/05/2015 às 16:41
18

A documentação "oficial"1 do git tem um recomendações sobre commits e mensagens. São um conjunto de boas práticas pra tornar a nevegação pelo hitórico do projeto mais fácil de assimilar.

Apesar de não serem obrigatórias, elas são fartamente aplicadas e replicadas pela internet:

  1. Verifique problemas de whitespace no código
    Essa é fácil, só executar git diff --check antes do commit, e qualquer erro de espaçamento extra vai ser listado.

  2. Commits devem ser mudanças pequenas e completas no código
    Duas coisas para se ter em mente é que um commit deve sempre funcionar sozinho. Se você implementou uma funcionalidade que levou 20 commits, cada um deles deve adicionar (ou remover) uma parte de maneira completa, e o programa deve continuar totalmente funcional. Isso não significa que os commits devem ser enormes, contendo centenas de linhas alteradas ao longo de dias. Procure fazer mudanças pequenas e incrementais.

  3. Formato da mensagem2
    Essa é uma parte tão essencial quanto as outras. Um projeto que mantém o mesmo padrão de mensagens é mais fácil de entender e acompanhar. Não faz muito sentido ser a única pessoa do projeto a trabalhar assim... Se você conseguir que todo mundo escreva as mensagens nesse formato, tudo vai ser mais fácil:

    1. Espaçamento de 1 linha entre o título do commit e o resto da mensagem
    2. O título deve ter no máximo 50 caracteres
    3. O título deve começar com letra maiúscula
    4. O título não deve terminar com '.'
    5. O título deve estar no presente da segunda pessoa:
      Ao invés de "Eu adicionei testes para" ou "Adicionando testes para", use "Adiciona testes para"
    6. Corpo da mensagem não deve ter largura maior que 72 caracteres
    7. Corpo da mensagem deve explicar o que e por que, não como.

    O exemplo na documentação do git:

    Breve (50 caracteres ou menos) resumo das mudanças
    
    Texto explicativo mais detalhado, se necessário. Separe em linhas de
    72 caracteres ou menos. Em alguns contextos a primeira linha é
    tratada como assunto do e-mail e o resto como corpo. A linha em branco
    separando o resumo do corpo é crítica (a não ser que o corpo não seja
    incluído); ferramentas como rebase podem ficar confusas se você usar
    os dois colados.
    
    Parágrafos adicionais vem após linhas em branco.
    
     - Tópicos também podem ser usados
    
     - Tipicamente um hífen ou asterisco é utilizado para marcar tópicos,
       precedidos de um espaço único, com linhas em branco entre eles, mas
       convenções variam nesse item
    

A dica final é que, se você registrar um editor default pro git com git config --global core.editor vim (por exemplo), é provável que o git inicie o editor com as configurações de formatação carregadas, pra te avisar caso você fuja do formato.


1. A documentação no git-scm.com é derivada de um livro que não foi escrito pelos autores do git, mas para todos os efeitos é considerada a documentação oficial. A versão em Português está defasada, mas essa parte não mudou muita coisa.

2. A lista de itens da formatação é derivada de How to Write a Git Commit Message (Como Escrever uma Mensagem de Commit - em Inglês). Eu gosto da maneira como a lista está organizada, por isso usei. Mas ela segue todas as recomendações da documentação oficial

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .