Como faço para convencer meus companheiros devs a querer adicionar comentários aos commits do código-fonte?

Concentre-se em "Por que". Está tudo muito bem olhando para os diffs e vendo que alguém mudou o fluxo lógico de uma seção de código ou algo assim, mas por que eles mudaram isso? O porquê é geralmente no ticket associado (JIRA para você).

Eles podem se perguntar por que o "Porquê" é importante, mas em 2 anos quando você detectou algum bug que causou essa mudança, saber por que isso foi feito é incrivelmente importante para não apenas consertar seu novo bug, mas certificando-se de que você não faça com que o bug antigo apareça novamente.

Existe também o motivo da auditoria. Encadernações de commits e IDs de ticket tornam realmente fácil dizer ok, estamos eliminando a Versão 2, isso corrige os defeitos 23, 25, 26 e 27, mas não há commits contra o defeito 24, então ainda é excelente.

Faça-os fazer as mesclagens e lidar com o suporte. Novamente, talvez você não esteja em condições de fazer isso, mas se você se encontrar sendo o único a solucionar um problema de um compromisso anterior educadamente, envie-o por cima do muro e diga. Não sei dizer o que você fez porque não há comentários de commit, você fez essas mudanças para descobrir.

Também para mesclar filiais. Não tenho certeza se isso cai em você ou não, mas essa é uma área que eu encontrei comentários úteis.

Novamente, não no seu barco, mas quando eu gerenciei uma equipe de software, eu disse a eles que, se fizessem bons comentários de commit, eu os usaria em um relatório de status semanal. Recebi excelentes commits depois desse e foi mais fácil para mim acompanhar o que estava acontecendo como o manager também.

Precisamos de comentários de check-in pelo mesmo motivo que precisamos de quebras de linha e espaçamento em nosso código. Para tornar as coisas mais fáceis de rastrear, compreenda ler e compreender.

Às vezes você precisa comparar o diff, mas muitas vezes você não precisa. Forçando os desenvolvedores a comparar quando tudo o que eles precisavam era ler 2-3 sentenças é uma perda total de tempo. Eu me pergunto por que eles não veem o valor do tempo do desenvolvedor.

• Dê um bom exemplo. Transforme suas próprias mensagens de commit em um exemplo brilhante de utilidade. Inclua referências a quaisquer outros sistemas que sua equipe use para gerenciar histórias e defeitos. Coloque uma breve declaração resumindo a mudança e uma boa explicação de por que a mudança é necessária e não outra em cada submissão.
• Sempre que a falta de uma mensagem de commit decente causar um trabalho extra, faça uma pergunta ao apresentador. Seja persistente com isso (mas não com um idiota).
• Se não estiver extrapolando sua função, escreva um script que envie um changelog diário usando as mensagens de confirmação. Isso dará credibilidade ao seu argumento de que as mensagens úteis têm um benefício além da navegação pelas revisões. Isso também pode ajudar a obter o gerenciamento do seu lado, já que eles verão o que acontece no dia a dia.
• Identifique seus aliados. Espero que haja pelo menos um outro indivíduo que concorde com você (talvez em silêncio, não discordando). Encontre essa pessoa ou essas pessoas e convença-as ainda mais para que você não fique sozinho.
• Quando a oportunidade de mencionar como as mensagens de confirmação decentes pouparam seu tempo (ou as mensagens ruins lhe custaram tempo) se apresenta, aproveite-a.

Não tenha medo de ser a roda estridente. Combater os maus hábitos de outras pessoas é frequentemente uma guerra de atrito.

Isso tem que ser uma das perguntas mais bizarras que já ouvi. As pessoas gastam horas ou até dias consertando algo e mais 2 segundos para digitar uma mensagem de commit é muito longa ?! Tenho que dizer que me preocuparia em trabalhar com pessoas de visão tão curta. Obviamente, eles não estão usando suas ferramentas nem perto de seu potencial total.

Aqui está um exemplo de uma revisão de código na qual eu estive envolvido na semana passada. Nosso software de controle de versão não preserva o histórico através de mesclagens, portanto, para alterações mais antigas, você precisa encontrar a ramificação exata em que foi criada, caso contrário, a mensagem de confirmação mostrará algo como "mesclado da ramificação Y". A ramificação Y pode mostrar "mesclada da ramificação Z" e uma ramificação com alguns níveis de aninhamento mais profunda na verdade tem a mensagem de confirmação real.

Um novo funcionário não sabia como rastrear o histórico corretamente, o que significa que ele estava basicamente trabalhando apenas com os diffs. Ele viu alguns códigos comentados relacionados ao bug que ele estava rastreando. Quando ele não comentou o código, seu bug foi embora. Ele assumiu que alguém havia comentado o código durante a depuração e, por engano, o registrou.

Isso não pareceu certo para alguns de nós durante a revisão do código, então eu rastreei a mensagem de commit real e descobri que havia um motivo válido para remover esse código um ano atrás. O novo funcionário conseguiu consertar seu código para corrigir o bug recém-descoberto sem reintroduzir o antigo.

Existem maneiras melhores de evitar a introdução desses tipos de regressões, como testes unitários completos, mas de alguma forma eu não vejo pessoas que não podem se incomodar com uma mensagem de confirmação de 2 segundos "desperdiçando" tempo em testes unitários.

Eu tive exatamente o mesmo problema aqui, então adicionei um gancho pré-compromisso para Subversion para que não seja aceito nenhum commit que não tenha começado com o número da Estória do Usuário (algum padrão básico correspondente para um formato esperado).

Não há nada que os impeça de entrar em 000-0000, mas uma vez que apenas um idiota disruptivo vai inventar um número quando tiver um número perfeitamente aceitável lá.

Eu fiz isso depois de passar dias tentando encontrar o que cria um conjunto de histórias de usuários. Sim, foi para lidar com uma falha de processo em outro lugar, mas ainda é incrivelmente informações valiosas para rastrear.

Bons comentários de commit são como qualquer boa documentação, um cache para seu cérebro lento e extinto ou um cache do resultado de qualquer análise / investigação demorada de depuração / problema.

Por exemplo sempre que você gasta tempo tentando descobrir alguma coisa, como depuração, análise de logs ou qualquer outra coisa, suas descobertas e resultados são preciosos. É claro que a maioria das tarefas pode ser repetida, mas isso pode levar tempo. Então você deve sempre documentar seus resultados.

Ainda assim, a documentação leva tempo e às vezes é sentida como desnecessária, como "só tivemos que fazer isso uma vez, então por que escrevê-la". Tudo bem, mas assim que você fizer a mesma coisa uma segunda vez porque você não documentou os resultados pela primeira vez, então é claro que é inteligente documentar os resultados.

Portanto, se seus colegas acharem que é muito trabalhoso adicionar comentários de commit, por exemplo, ao menos apontar para o caso Jira / Ticket que eles estavam resolvendo, bem, eles podem ser motivados pela pressão de responder constantemente a perguntas sobre o razão para cada changeset.

Na minha opinião, a documentação deve ser produzida em função da informação solicitada. Por exemplo, correspondência por correio é um bom sistema de documentação. As perguntas recebem respostas que podem ser recuperadas posteriormente, é assim que as listas de discussão e os fóruns funcionam na prática como bases de conhecimento.

Infelizmente, onde trabalho, o e-mail é excluído automaticamente após três meses, por isso nem sempre funciona na prática.

Procure perdão, não permissão.

Enquanto dura, eu fiz exatamente isso. Eu tinha uma divisão 50/50 entre pessoas que apoiavam e pessoas que se opunham, a maioria das quais eram do mesmo nível que eu no grupo. Os argumentos foram "Eu não posso ser incomodado" e "Qual é o ponto?". (Ambos indicando apatia e preguiça, não preocupações genuínas).

Eu adicionei o pre-commit hook que simplesmente mediu o comprimento da string e deu uma mensagem um pouco engraçada antes de rejeitá-la. Eu coloquei meu nome na mensagem, então a responsabilidade por "esse ultraje" era clara. É claro que "a oposição" poderia facilmente removê-lo, mas cavar os scripts exigiria mais esforço do que adicionar mais um comentário!

Por uma semana recebi mensagens adicionadas como * * (expletive deleted) ou kjhfkwhkfjhw. Depois disso, mensagens básicas começaram a aparecer.

Um ano depois, os céticos usam comentários maldosos e admitem o quanto eram míopes. Eu nunca poderia ter um consenso, mas certamente tenho perdoados e talvez credibilidade. Funciona, as pessoas usam.

Se você quisesse ser mais agradável (ou achar que se meteria em problemas), peça permissão para adicionar um gancho de confirmação por um período de teste. Digamos que, se as pessoas não gostarem daqui a duas semanas ou quatro semanas, você as retirará. As chances são que eles vão perder o interesse ... ou crescer para gostar.

Eu costumo convencer as pessoas através de:

• dialética com boas razões de apoio
• liderando pelo exemplo
• atrito

Se eu quisesse que nossa equipe fizesse algo ruim o suficiente, eu continuaria importunando até conseguir o que queria. Eu tento incomodar durante os momentos em que posso apontar que poderíamos ter economizado tempo / dinheiro se já estivéssemos fazendo X.

Outras boas razões para cometer comentários:

• Gerando o ChangeLog automaticamente a partir dos comentários.
• Trilha de auditoria para correções de bugs, adições de recursos. Isso é útil dentro e fora da equipe.
• Torne o e-mail de confirmação mais útil.
• Impede-me de perguntar ao desenvolvedor o que o commit X faz (depois de quase todo commit).

• Verifique os registros do SVN em busca de algo obscuro feito há 6 meses.
• Faça algumas perguntas sobre essa coisa sem saber quando isso foi feito
• ???
• Lucro

Como você os faz querer adicionar bons comentários?

De uma experiência com um colega que acabei de ter. No final de um projeto, tivemos que escrever um documento resumido de todas as mudanças feitas ao longo do projeto. Não tendo feito boas notas de commit, meu colega achou esta tarefa bastante demorada, e agora mudou para fazer comentários bastante longos com cada commit.

Então - o takeaway - uma solução poderia ser que os desenvolvedores escrevessem documentos de resumo no final do projeto detalhando quais mudanças foram feitas em quais arquivos, quais arquivos foram adicionados / removidos e por quê.

Propor isso ao gerenciamento a portas fechadas:

O pior cenário acontece: todos os desenvolvedores de nível sênior saem pela porta.

À medida que a empresa se esforça para preencher as vagas vazias do desenvolvedor, a equipe de gerenciamento é encarregada de comunicar o estado do sistema ao cliente.

Pergunte a eles o que eles acham que facilitaria o trabalho deles na reconstrução do histórico do aplicativo:

Lendo confirmações simples de inglês que descrevem claramente o estado de mudança do sistema?

Ou eles prefeririam analisar as diferenças de código e descobrir por si próprios?

Eu acho que uma maneira de convencê-los seria realmente sentir a dor que você está sentindo.

Por exemplo, digamos que eles estão trabalhando no seguinte problema: Eles têm um bug que, de alguma forma, apareceu quando outro bug corrigido para o mesmo código (oh a ironia) foi implementado. Ser capaz de procurar isso apenas pesquisando através das mensagens de commit seria ótimo (e, assim, descobrir quem o escreveu).

Outra maneira seria explicar a eles que a mensagem de commit pode ser útil para dar uma dica de por que algo foi implementado de uma certa maneira. Mesmo que a mensagem de confirmação diga apenas "recurso X", você ainda pode ter uma pista sobre quem a implementou, para saber com quem conversar.

However, this doesn't seem to be enough to combat the two responses I always get:

1. It takes too long and I just want to get my changes into the repo.
2. It's easy enough to just look at the diffs.

Você já tentou derrubar um desafio para seus colegas desenvolvedores para que eles obtenham algum outro benefício se incluírem comentários? Pode-se olhar para isso de dois ângulos diferentes:

1. Melhorando o jogo deles - Essa pode ser a perspectiva mais difícil de fazer, mas a ideia aqui é que eles façam isso por algum tempo e se acostumem com a ideia, então o hábito é que levaria mais tempo para ir para o outro lado . Outro ponto aqui é quanto escrutínio os comentários receberiam? Se você está querendo um conto no comentário eu pude entender o ponto deles.
2. Subsidiando uma mudança - Aqui é onde você tem algum tipo de concurso como forma de ter o buy-in inicial para tentar isso ou oferecer algum outro tipo de incentivo para que a mudança seja feita por um tempo. / li>

Outra coisa a considerar é o quão bem você sabe o que seus colegas desenvolvedores estão gerenciando onde você trabalha? Se eles estão tentando fazer 10 coisas ontem, então eu poderia entender que eles podem não querer mudar o que eles vêem como algo que já funciona. Você está tentando dizer a eles: "Não, isso não funciona?" Se assim for, então eu posso ver como eles podem ser um pouco defensivos ou combativos sobre isso. Se você está tentando dizer a eles: "Enquanto isso pode funcionar, existe uma alternativa que pode ser melhor ...", então você pode ter uma chance. Ter uma atitude "mais santo do que tu" não vai ajudá-lo, IMO.

Outra maneira de ver isso é como uma maneira de o (s) desenvolvedor (es) envolvido (s) desenvolver suas carreiras - eles devem possuir o documentação do seu trabalho.

Além de outros pontos levantados no artigo acima mencionado, há a capacidade de poder revisar as alterações de código para descobrir onde / quando / por que uma alteração foi feita. Isso pode ser vital ao rastrear um bug indescritível.

Depois de convencê-los de que é importante comentar seus commits, você pode criar um script que force comentários sobre commits, caso contrário ele falhará. Você pode especificar um mínimo de caracteres para garantir um comentário significativo. Isso os ajudará a "lembrar".

No entanto, é importante que eles entendam o Why como o @Kevin disse, ou então eles simplesmente adicionarão qualquer comentário aleatório.

Você tem revisões de código? Uma coisa que pode ajudar é instituir uma regra de que qualquer consolidação ou mesclagem deve ser analisada e aprovada por outro desenvolvedor. Então, se você é o revisor, você teria que pedir ao desenvolvedor que faça o commit para explicar a você o que ele fez. Assim que ele fizer isso, você deve pedir a ele que digite no comentário o que ele acabou de lhe dizer. Muitas vezes, quando não se pode explicar coerentemente as mudanças feitas, isso significa que essas mudanças não deveriam ter sido feitas em primeiro lugar.

Eu tenho que dizer, porém, como as pessoas podem se opor a algo tão obviamente útil quanto cometer comentários? Não demora muito, e é um tempo bem gasto. Escrever um comentário obriga você a pensar sobre o que acabou de fazer. Pode até fazer com que você olhe para os diffs para ter certeza de que realmente fez o que acha que fez, e que não fez nada estúpido.

Quando você não escreve os comentários, você está sendo desleixado e indisciplinado. E se você insiste que você não deve ser obrigado a escrever os comentários, então você está sendo deliberadamente negligente.

Diga-lhes que é a única maneira de ter uma chance de manter sua bagunça processual de 50.000 métodos de linha, então considere escrever um código melhor e mais explícito no futuro para que você não tenha que lidar com um monte de comentários inúteis. base de código.

Este é um item de alteração de processo: Peça a um gerente que atribua o código desenvolvido por "x" a "Y" para verificações de garantia de qualidade somente no código, incluindo o controle de qualidade dos comentários.

Na minha própria organização, os desenvolvedores não podem realizar o controle de qualidade final do seu próprio código e fazer o check-in. Isso deve ser feito por outro desenvolvedor. Parte do QA Check é de comentários, portanto, nenhum comentário, nenhum check-in. Fazemos muitos contratos onde nossa "arte" é na verdade propriedade intelectual contratual de outra pessoa, para que outros precisem entender e alavancar nosso código. Além disso, há momentos em que os projetos voltam para nós depois de um longo hiato e precisamos ser capazes de pegar o código de 18 a 24 meses depois e entender o porquê, onde e como chegamos ao artefato de código à nossa frente. Isso fornece uma motivação egoísta para escrever comentários de compromisso.

Peça e faça com que seus colegas desenvolvedores façam algumas mesclagens, pesquise histórico e compare alguns arquivos do histórico.

Provavelmente, eles pedirão que você coloque comentários no dia seguinte.

Aqui estão alguns conselhos:

1. Não tente mudar o mundo. Você irá falhar.
2. Em vez disso, você deve reconhecer que todos trabalham de maneira um pouco diferente. Nenhum tamanho serve para todos.
3. exigir alguns passos específicos para os processos de trabalho das pessoas é muito maléfico. Alterar esses processos leva 10 anos. Você está pedindo para fazer isso antes do próximo prazo.
4. Até mesmo alterações simples no processo podem demorar muito tempo.
5. Alguns pequenos comentários sobre commits são muito insignificantes para alterar esses processos.
6. Você pode assumir que eles fazem um trabalho de qualidade, mas devem dar liberdade suficiente para escolher os próprios passos. Algumas etapas complicadas podem não ser necessárias para desenvolvedores experientes.
7. Se você é babá de novatos, processos mais strongs podem ser necessários, mas desenvolvedores experientes não devem lidar com besteiras.
8. A imposição de restrições draconianas sobre como o trabalho deve ser feito nunca vai funcionar, só pode retardar as pessoas (pode ser bom se elas forem muito rápidas)
9. Existem muitas pessoas que pensam que o jeito delas é o único jeito certo de fazer as coisas. Espero que você não seja um deles.

Se o controle de origem o provar, ative os comentários obrigatórios para evitar qualquer comentário não comentado. Simples o suficiente e todos logo perceberão que 5 segundos de digitação de um comentário é indolor.

Mas os commits não comentados são um dos menores negativos que existem. Eu fiz parte de muitos projetos de sucesso onde nem um único commit foi comentado. Não coloque a sua calcinha em cima dela.