Como convencer meus colegas desenvolvedores a querer adicionar comentários às confirmações do código-fonte?

Eu sei que o Subversion (o que estamos usando no trabalho) pode ser configurado para exigir comentários em confirmações, no entanto, não estou em posição de poder para simplesmente ativá-lo. Sei que meu motivo para comentar meus commits é porque é útil, mesmo que apenas como um ativador de memória, entender rapidamente o motivo por trás do commit. No entanto, isso não parece ser suficiente para combater as duas respostas que sempre recebo:

1. Leva muito tempo e só quero incluir minhas alterações no repositório.
2. É fácil o suficiente apenas olhar para as diferenças.

Eu até mostro a eles o valor de simplesmente inserir um ID de problema do JIRA e como ele se vincula automaticamente ao problema, mas ainda não há dados com eles.

O pior de tudo é que a pessoa que pode fazer a ligação está no mesmo campo: não quer se incomodar e fica bem em olhar as diferenças.

Eu sei que é a coisa certa a fazer, mas como posso fazê-los ver a luz? Mesmo se eu não consigo convencer meus colegas desenvolvedores, como posso convencer a gerência de que é a coisa certa a fazer pelos negócios?

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

Eles podem se perguntar por que o "Por que" é importante, mas em 2 anos quando você detectou algum bug que é um efeito colateral dessa alteração, saber por que isso foi feito é incrivelmente importante não apenas para corrigir seu novo bug, mas também para garantir que você não faz com que o bug antigo reapareça.

Há também o motivo da auditoria. Confirmações de vinculação e IDs de ticket facilitam a resposta, estamos atualizando a Versão 2, isso corrige os defeitos 23, 25, 26 e 27, mas não há confirmações contra o defeito 24, por isso ainda está pendente.

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

Também para mesclar ramificações. Não tenho certeza se isso recai sobre você ou não, mas essa é uma área em que achei comentários úteis.

Novamente, não no seu barco, mas quando gerenciei uma equipe de software, disse a eles que, se eles fizessem bons comentários, eu os usaria em um relatório semanal de status. Obtive excelentes commits após esse e foi mais fácil para mim acompanhar o que estava acontecendo como gerente 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 facilitar o rastreamento, compreenda a leitura e a compreensão.

Às vezes, você precisa comparar, mas geralmente não. Forçar os desenvolvedores a comparar, quando tudo o que eles precisavam era ler 2-3 frases, é uma total perda de tempo. Eu me pergunto por que eles não vêem o valor do tempo do desenvolvedor.

• Dê um bom exemplo. Faça de suas próprias mensagens de confirmação um exemplo brilhante de utilidade. Inclua referências a quaisquer outros sistemas que sua equipe use para gerenciar histórias e defeitos. Faça 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 coisa em cada envio.
• Sempre que a falta de uma mensagem de confirmação decente causar trabalho extra, faça uma pergunta ao remetente. Seja persistente com isso (mas não com um idiota).
• Se não estiver ultrapassando sua função, escreva um script que envie um registro de alterações 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 de navegar pelas revisões. Isso também pode ajudar a manter o gerenciamento do seu lado, pois eles verão o que está acontecendo diariamente.
• Identifique seus aliados. Espero que haja pelo menos uma outra pessoa que concorde com você (talvez por não concordar silenciosamente). 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 consolidação decentes poupam tempo (ou mensagens ruins custam tempo) se apresentar, aproveite-o.

Não tenha medo de ser a roda estridente. Lutar contra os maus hábitos de outras pessoas costuma ser uma guerra de desgaste.

Essa deve ser uma das perguntas mais bizarras que eu já ouvi. As pessoas passam horas ou até dias consertando algo e mais 2 segundos para digitar uma mensagem de confirmação é muito longa ?! Devo dizer que me preocuparia em trabalhar com pessoas míopes. Obviamente, eles não estão usando suas ferramentas para se aproximar de todo o seu potencial.

Aqui está um exemplo de uma revisão de código em que estive envolvido na semana passada. Nosso software de controle de versão não preserva o histórico nas mesclagens, portanto, para alterações mais antigas, é necessário encontrar a ramificação exata em que foi feita; caso contrário, a mensagem de confirmação mostra algo como "mesclado da ramificação Y". A ramificação Y pode mostrar "mesclada da ramificação Z", e uma ramificação alguns níveis de aninhamento mais profundo 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 as diferenças. Ele viu algum código comentado relacionado ao bug que estava rastreando. Quando ele descomentou o código, seu bug foi embora. Ele assumiu que alguém havia comentado o código durante a depuração e o fez por engano.

Isso não pareceu certo para alguns de nós durante a revisão do código, então localizei a mensagem de confirmação real e descobri que havia um motivo válido para remover esse código há um ano. 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 de unidade completos, mas, de alguma forma, não vejo pessoas que não possam se incomodar com uma mensagem de confirmação de 2 segundos "desperdiçando" tempo no teste de unidade.

Eu tinha exatamente o mesmo problema aqui, então adicionei um gancho de pré-confirmação ao Subversion para que ele não aceitasse nenhum commit que não fosse iniciado com o número da história do usuário (alguns padrões básicos correspondentes para o formato esperado).

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

Fiz isso depois de passar dias tentando descobrir em quais construções um conjunto de histórias de usuários foi inserido. Sim, era para lidar com uma falha de processo em outro lugar, mas ainda é uma informação incrivelmente valiosa para rastrear.

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

Por exemplo, sempre que você dedica algum tempo a descobrir algo, 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. Portanto, 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 anotá-la". Tudo bem, mas assim que você faz a mesma coisa uma segunda vez porque não documentou os resultados pela primeira vez, é claro que é inteligente documentar os resultados.

Portanto, se seus colegas acharem muito trabalho adicionar comentários de confirmação, por exemplo, pelo menos aponte para o caso / Ticket Jira que eles estavam solucionando, bem, eles podem ser motivados pela pressão de responder constantemente às perguntas sobre o motivo de cada um. changeset.

Na minha opinião, a documentação deve ser produzida em função da informação solicitada. Por exemplo, a correspondência é 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 email é excluído automaticamente após três meses, portanto nem sempre funciona na prática.

Busque perdão, não permissão.

Embora duro, eu fiz exatamente isso. Eu tinha uma divisão de 50/50 entre as pessoas que apoiavam e as que se opunham, a maioria dos quais estavam no mesmo nível que eu no grupo. Os argumentos foram "Não posso me incomodar" e "Qual é o objetivo?". (Ambos indicando apatia e preguiça, não preocupações genuínas).

Adicionei um gancho de pré-confirmação que simplesmente media o comprimento da corda e dava uma mensagem levemente engraçada antes de rejeitá-la. Coloquei meu nome na mensagem para que a responsabilidade por "esse ultraje" fosse clara. É claro que "a oposição" poderia removê-lo facilmente, mas investigar os scripts exigiria mais esforço do que adicionar mais um comentário!

Por uma semana, recebi mensagens adicionadas como * * (palavrão excluído) ou kjhfkwhkfjhw. Depois disso, as mensagens básicas começaram a aparecer.

Um ano depois, os céticos usam comentários significativos e, na verdade, admitem como eram míopes. Eu nunca poderia ter conseguido consenso, mas certamente recebi perdões e talvez credibilidade. Funciona, as pessoas usam.

Se você quiser ser mais agradável (ou achar que terá problemas), peça permissão para adicionar um gancho de confirmação por um período de teste. Diga que se as pessoas não gostarem em 2 ou 4 semanas, você o retirará. As chances são de que eles vão perder o interesse ... ou passar a gostar.

Eu normalmente 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, continuaria incomodando até conseguir o que queria. Eu tento incomodar durante aqueles momentos em que posso apontar que poderíamos ter economizado tempo / dinheiro se já estivéssemos fazendo X.

Boas razões adicionais para enviar comentários:

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

• Verifique seus logs SVN para ver se há algo obscuro feito há 6 meses.
• Faça algumas perguntas sobre isso sem dizer quando 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 alterações feitas ao longo do projeto. Não tendo feito boas anotações de confirmação, meu colega considerou essa tarefa bastante demorada e agora passou a fazer comentários bastante longos com cada confirmação.

Portanto - a solução - uma solução poderia ser fazer com que os desenvolvedores escrevessem documentos de resumo no final do projeto, detalhando quais alterações foram feitas em quais arquivos, quais arquivos foram adicionados / removidos e por quê.

Propor isso à gerência a portas fechadas:

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

Enquanto a empresa luta para preencher vagas vazias de desenvolvedores, a equipe de gerenciamento é encarregada de comunicar o estado do sistema ao cliente.

Pergunte a eles o que eles acham que facilitaria seu trabalho na reconstrução da história do aplicativo:

Lendo compromissos simples em inglês que descrevem claramente o estado em mudança do sistema?

Ou eles preferem olhar as diferenças de código e descobrir por si mesmas?

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

Por exemplo, digamos que eles estejam trabalhando no seguinte problema: Eles têm um bug que, de alguma forma, apareceu quando outra correção de bug para o mesmo código (ah, a ironia) foi implementada. Ser capaz de pesquisar isso apenas pesquisando nas mensagens de confirmação seria ótimo (e, assim, descobrir quem o escreveu).

Outra maneira seria explicar a eles que a mensagem de confirmação 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 idéia de quem a implementou, para saber com quem conversar.

No entanto, isso não parece ser suficiente para combater as duas respostas que sempre recebo:

1. Leva muito tempo e só quero incluir minhas alterações no repositório.
2. É fácil o suficiente apenas olhar para as diferenças.

Você já tentou lançar um desafio a seus colegas desenvolvedores para que eles recebessem algum outro benefício ao colocar comentários? Pode-se olhar para isso de dois ângulos diferentes:

1. Aprimorando o jogo - Essa pode ser a perspectiva mais complicada a ser adotada, mas a idéia aqui é que eles façam isso por um certo período de tempo e se acostumem com a ideia, de modo que o hábito seja que demore mais para seguir o caminho inverso. Outro ponto aqui é quanto escrutínio os comentários receberiam? Se você está querendo uma história curta no comentário, eu poderia entender o ponto deles.
2. Subsidiando uma mudança - É aqui que você tem algum tipo de concurso como forma de obter o buy-in inicial para tentar isso ou oferece algum outro tipo de incentivo para que a mudança seja feita por um tempo.

Outra coisa a considerar é 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 pude entender que eles podem não querer mudar o que vêem como algo que já funciona. Você está tentando dizer a eles: "Não, isso não funciona?" Nesse caso, posso ver como eles podem ser um pouco defensivos ou combativos. Se você está tentando dizer a eles: "Embora isso possa funcionar, há uma alternativa que pode ser melhor ...", então você pode ter uma chance. Ter uma atitude "mais santa do que tu" aqui não vai ajudá-lo, IMO.

Outra maneira de ver isso é como o desenvolvedor envolvido em crescer suas carreiras - eles devem possuir a documentação de seu trabalho.

Além de outros pontos levantados no artigo mencionado acima, há a capacidade de 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 esquivo.

Depois de convencê-los de que é importante comentar suas confirmações, você pode criar um script que force os comentários nas confirmações, caso contrário, falhará. Você pode até especificar um mínimo de caracteres para garantir um comentário significativo. Isso irá ajudá-los a "lembrar".

No entanto, é importante que eles entendam o Por que, como o @Kevin disse, ou então eles apenas adicionam qualquer comentário aleatório.

Você tem análises de código? Uma coisa que pode ajudar é instituir uma regra na qual qualquer confirmação ou fusão deve ser examinada e aprovada por outro desenvolvedor. Então, se você é o revisor, terá que pedir ao desenvolvedor que está se comprometendo a explicar o que ele fez. Quando ele o fizer, peça que ele digite no comentário o que ele acabou de lhe dizer. Freqüentemente, quando não se pode explicar coerentemente as mudanças que fez, significa que essas mudanças não deveriam ter sido feitas em primeiro lugar.

Devo dizer, porém, como as pessoas podem se opor a algo tão obviamente útil quanto enviar comentários? Não demora muito, e é um tempo bem gasto. Escrever um comentário obriga a pensar no que acabou de fazer. Pode até fazer com que você observe as diferenças para garantir que realmente fez o que acha que fez e que não fez nada estúpido.

Quando você não escreve os comentários, está sendo desleixado e indisciplinado. E se você insistir em não escrever os comentários, estará sendo deliberadamente negligente.

Diga a eles que é a única maneira de ter a chance de manter sua confusão processual de 50.000 métodos de linha e considere escrever um código melhor e mais explícito no futuro, para que você não precise lidar com muitos comentários inúteis inchando sua base de códigos.

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

Na minha própria organização, os desenvolvedores não têm permissão para executar o controle de qualidade final de seu próprio código e fazer o check-in; isso deve ser feito por outro desenvolvedor. Parte da verificação de controle de qualidade consiste em comentários, portanto, não há comentários, não há check-in. Realizamos muitos trabalhos contratuais em que nossa "arte" é na verdade propriedade intelectual contratual de outra pessoa, para que outras pessoas precisem entender e aproveitar nosso código. Além disso, há momentos em que os projetos retornam para nós após um longo hiato e precisamos ser capazes de pegar o código 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 confirmação.

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

As chances são de que eles pedirão que você faça comentários no dia seguinte.

Aqui estão alguns conselhos:

1. Não tente mudar o mundo. Você vai falhar.
2. Em vez disso, você deve reconhecer que todos funcionam de maneira um pouco diferente. Nenhum tamanho serve para todos.
3. exigir algumas etapas específicas nos processos de trabalho das pessoas é muito ruim. Alterar esses processos leva 10 anos. Você está pedindo que eles façam isso antes do próximo prazo.
4. Mesmo mudanças simples no processo podem levar muito tempo.
5. Alguns pequenos comentários sobre confirmações são muito insignificantes para alterar esses processos.
6. Você pode presumir que eles fazem um trabalho de qualidade, mas deve dar liberdade suficiente para escolher os passos. Algumas etapas onerosas podem não ser necessárias para desenvolvedores experientes.
7. Se você está cuidando de novatos, então processos mais fortes 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 funcionará, pois só pode atrasar as pessoas (pode ser bom se forem muito rápidas)
9. Muitas pessoas pensam que seu caminho é o único caminho certo para fazer as coisas. Espero que você não seja um deles.

Se o seu controle de origem o provar, ative os comentários obrigatórios para evitar quaisquer compromissos não comentados. Simples o suficiente e todos logo perceberão que 5 segundos de digitação de um comentário são indolores.

Mas commits não comentados é um dos menores negativos que existem. Eu participei de muitos projetos bem-sucedidos nos quais nenhum único commit foi comentado. Não coloque sua calcinha em cima dela.