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?
2 Respostas
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.
-
2
-
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.– utluizCommented 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. Commented 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.– GabeCommented 5/05/2015 às 16:41
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:
Verifique problemas de whitespace no código
Essa é fácil, só executargit diff --check
antes do commit, e qualquer erro de espaçamento extra vai ser listado.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.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:- Espaçamento de 1 linha entre o título do commit e o resto da mensagem
- O título deve ter no máximo 50 caracteres
- O título deve começar com letra maiúscula
- O título não deve terminar com '.'
- 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" - Corpo da mensagem não deve ter largura maior que 72 caracteres
- 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
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.