Comment convaincre mes collègues développeurs de VOULOIR ajouter des commentaires aux commits de code source?

Je sais que Subversion (ce que nous utilisons au travail) peut être configuré pour exiger des commentaires sur les commits, mais je ne suis pas en position de pouvoir simplement l'activer. Je sais que la raison pour laquelle je commente mes commits est parce qu’il est utile, ne serait-ce qu’en tant que jogeur de mémoire, de comprendre rapidement le motif du commet. Cependant, cela ne semble pas être suffisant pour combattre les deux réponses que je reçois toujours:

1. Cela prend trop de temps et je veux juste que mes modifications soient stockées dans le repo.
2. Il est assez facile de regarder les diffs.

Je leur ai même montré l'intérêt de simplement mettre un identifiant de problème JIRA et comment il est automatiquement lié au problème, mais toujours pas de dés avec eux.

Le pire de tout, la personne qui peut faire l'appel est dans le même camp: ne veut pas déranger et est bon pour regarder des diffs.

Je sais que c'est la bonne chose à faire, mais comment puis-je leur faire voir la lumière? Même si je n'arrive pas à convaincre mes collègues développeurs, comment puis-je convaincre la direction que c'est la bonne chose à faire pour l'entreprise?

Focus sur "Pourquoi". C'est très bien de regarder les diffs et de voir que quelqu'un a changé le flux logique d'une section de code ou quelque chose du genre, mais pourquoi l'ont-ils changé? Le pourquoi se trouve généralement dans le ticket associé (JIRA pour vous).

Ils peuvent se demander pourquoi le "Pourquoi" est important, mais dans deux ans, lorsque vous aurez détecté un bogue provoquant ce changement, il est extrêmement important de savoir pourquoi cela a été fait, non seulement pour corriger votre nouveau bogue, mais aussi pour vous en assurer. vous ne faites pas réapparaître l'ancien bug.

Il y a aussi la raison de l'audit. Les commits de reliure et les identifiants de ticket rendent très facile de dire ok, nous sortons la version 2, cela corrige les défauts 23, 25, 26 et 27, mais il n'y a pas de validations contre le défaut 24, il est donc toujours en attente.

Faites-les faire les fusions et traiter avec le soutien. Encore une fois, vous n'êtes peut-être pas en mesure de le faire, mais si vous vous retrouvez seul à résoudre un problème lié à un engagement précédent, envoyez-le poliment par-dessus la clôture et dites-le. Je ne peux pas dire ce que vous avez fait car il n'y a pas de commentaires de validation, vous avez apporté ces modifications dont vous avez besoin pour le comprendre.

Aussi pour la fusion des branches. Je ne sais pas si cela vous incombe ou non, mais c’est un domaine dans lequel j’ai trouvé les commentaires utiles.

Encore une fois, pas dans votre bateau, mais quand je dirigeais une équipe de logiciels, je leur disais que s'ils faisaient de bons commentaires sur les commits, j'utiliserais ceux qui se trouvent dans un rapport de situation hebdomadaire. J'ai obtenu d'excellents commits après celui-ci et il était plus facile pour moi de suivre ce qui se passait en tant que responsable.

Nous avons besoin des commentaires d’enregistrement pour la même raison que nous avons besoin de sauts de ligne et d’espacement dans notre code. Pour faciliter la recherche, comprendre, lire et comprendre.

Parfois, vous avez besoin de comparer, mais souvent vous ne le faites pas. Forcer les développeurs à se comparer lorsque tout ce dont ils avaient besoin était de lire deux ou trois phrases est une perte de temps totale. Je me demande pourquoi ils ne voient pas la valeur du temps de développement.

• Donner le bon exemple. Faites de vos propres messages un exemple brillant d’utilité. Incluez des références à tout autre système utilisé par votre équipe pour gérer les récits et les anomalies. Mettez une brève déclaration résumant le changement et une bonne explication de la raison pour laquelle le changement est nécessaire et non pas autre chose dans chaque soumission.
• Chaque fois que l’absence d’un message de validation décent vous impose un travail supplémentaire, posez une question à l’envoyeur. Soyez persistant avec cela (mais pas un imbécile).
• Si cela ne dépasse pas votre rôle, écrivez un script qui envoie un journal quotidien des modifications en utilisant les messages de validation. Cela confèrera de la crédibilité à votre argument selon lequel des messages utiles ont un avantage au-delà de la consultation de révisions. Cela pourrait également aider à obtenir la gestion de votre côté, car ils vont voir au jour le jour ce qui se passe.
• Identifiez vos alliés. J'espère qu'il y a au moins une autre personne qui est d'accord avec vous (peut-être en silence, pas en désaccord). Trouvez cette personne ou ces personnes et persuadez-les davantage afin que vous ne soyez pas seul.
• Lorsque l'occasion de mentionner comment des messages de commit décents vous ont fait gagner du temps (ou que de mauvais messages vous ont coûté du temps) se présente, saisissez-la.

N'ayez pas peur d'être la roue qui grince. Combattre les mauvaises habitudes des autres peuples est souvent une guerre d'usure.

Ce doit être l'une des questions les plus bizarres que j'ai entendues. Les gens passent des heures voire des jours à réparer quelque chose et 2 secondes de plus pour taper un message de validation est trop long?! Je dois dire que je m'inquiéterais de travailler avec des personnes aussi myopes. Ils n'utilisent évidemment pas leurs outils pour atteindre leur plein potentiel.

Voici un exemple tiré d'une revue de code à laquelle j'ai participé la semaine dernière. Notre logiciel de contrôle de version ne conserve pas l'historique des fusions. Par conséquent, pour les modifications plus anciennes, vous devez trouver la branche exacte dans laquelle elle a été créée, sinon le message de validation affiche simplement quelque chose comme "fusionné à partir de la branche Y". La branche Y peut indiquer "fusionnée à partir de la branche Z", et une branche à quelques niveaux d'imbrication plus profond contient en réalité le message de validation réel.

Un nouvel employé ne savait pas comment retracer l'historique correctement, ce qui signifie qu'il travaillait essentiellement avec les diffs. Il a vu du code commenté lié au bogue qu'il traquait. Quand il décommenta le code, son bug disparut. Il a supposé que quelqu'un avait commenté le code lors du débogage et l'avait archivé par erreur.

Cela ne nous convenait pas à quelques-uns lors de la révision du code. J'ai donc retracé le vrai message de validation et découvert qu'il y avait une raison valable de supprimer ce code il y a un an. Le nouvel employé a pu corriger son code pour corriger le nouveau bogue découvert sans réintroduire l'ancien.

Il existe de meilleurs moyens d'éviter d'introduire ce type de régression, par exemple des tests unitaires approfondis, mais je ne vois pas du tout les personnes qui ne s'embarrassent pas avec un message de validation de 2 secondes "gaspillant" du temps en tests unitaires.

J'avais exactement le même problème ici, alors j'ai ajouté un point d' ancrage pré-commit à Subversion afin qu'il n'accepte pas les commits qui ne commencent pas par le numéro User Story (un modèle de base correspondant au format attendu).

Rien ne les empêche de rentrer dans 000-0000, mais une fois, seul un idiot perturbateur composera un numéro quand ils auront un nombre parfaitement acceptable.

Je l’ai fait après avoir passé des jours à essayer de trouver ce qui construisait un ensemble d’histoires d’utilisateur. Oui, il s'agissait de faire face à une défaillance de processus ailleurs, mais il reste des informations extrêmement précieuses à suivre.

Les bons commentaires de commit sont comme toute bonne documentation, un cache pour votre cerveau lent et défunt ou un cache du résultat de toute longue analyse / investigation de débogage / problème.

Par exemple, chaque fois que vous passez du temps à trouver quelque chose, comme le débogage, l'analyse de journaux ou autre, vos découvertes et résultats sont précieux. Bien sûr, la plupart des tâches peuvent être répétées, mais cela peut prendre du temps. Donc, vous devriez toujours documenter vos résultats.

Néanmoins, la documentation prend du temps et parfois elle est jugée inutile, comme "nous n’avions à le faire qu’une seule fois, alors pourquoi l’écrire". C'est bien, mais dès que vous faites la même chose une seconde fois parce que vous n'avez pas documenté les résultats la première fois, il est bien sûr astucieux de documenter les résultats.

Donc, si vos collègues estiment que l'ajout de commentaires d'engagement est un travail trop compliqué, par exemple, au moins qu'ils pointent l'affaire Jira / Ticket qu'ils résolvaient, eh bien, ils pourraient être motivés par la pression qui leur est donnée de répondre sans cesse à des questions concernant le motif de chacun changeset.

À mon avis, la documentation devrait être produite en fonction des informations demandées. Par exemple, la correspondance postale est un très bon système de documentation. Les questions reçoivent des réponses qui peuvent être récupérées ultérieurement. C'est ainsi que les listes de diffusion et les forums fonctionnent en pratique en tant que bases de connaissances.

Malheureusement, là où je travaille, le courrier est automatiquement supprimé au bout de 3 mois, de sorte qu'il ne fonctionne pas toujours dans la pratique.

Demander pardon, pas la permission.

Bien que dur, j'ai fait juste cela. Je partageais à parts égales les personnes en faveur et les personnes en opposition, dont la plupart étaient du même niveau que moi dans le groupe. Les arguments étaient "Je ne peux pas être dérangé" et "Quel est le but?". (Les deux indiquant l'apathie et la paresse, pas de préoccupations sincères).

J'ai ajouté un crochet de pré-validation qui mesurait simplement la longueur de la chaîne et donnait un message légèrement humoristique avant de le rejeter. J'ai mis mon nom dans le message afin que la responsabilité de "cet outrage" soit claire. Bien sûr, "l'opposition" pourrait facilement l'enlever, mais creuser dans les scripts demanderait plus d'effort que d'ajouter un commentaire de plus!

Pendant une semaine, j'ai reçu des messages comme * * (suppression supprimée) ou kjhfkwhkfjhw. Après cela, les messages de base ont commencé à apparaître.

Un an plus tard, les sceptiques utilisent des commentaires mesquins et admettent à quel point ils étaient myopes. Je n'aurais jamais pu obtenir un consensus, mais j'ai certainement eu le pardon et peut-être la crédibilité. Cela fonctionne, les gens l'utilisent.

Si vous vouliez être plus sympathique (ou si vous sentiez que vous auriez des problèmes), demandez la permission d'ajouter un hook de commit pour une période d'essai. Dites que si les gens ne l'aiment pas dans 2 ou 4 semaines, vous le retirerez. Les chances sont, ils vont perdre intérêt ... ou grandir à aimer ça.

Je convainc généralement les gens à travers:

• dialectique avec de bonnes raisons
• donner l'exemple
• usure

Si je voulais que notre équipe fasse quelque chose d'assez grave, je continuerais à harceler jusqu'à ce que je réussisse. J'essaie de harceler pendant ces moments où je peux dire que nous aurions pu gagner du temps / de l'argent si nous avions déjà fait X.

Autres bonnes raisons pour les commentaires d'engagement:

• Générer automatiquement ChangeLog à partir des commentaires.
• Audit trail pour les corrections de bugs, ajouts de fonctionnalités. Ceci est utile à la fois dans et en dehors de l'équipe.
• Rendre le courrier valide plus utile.
• Arrêtez-moi de demander au développeur ce que commit X (après presque chaque commit).

• Vérifiez vos journaux SVN pour quelque chose d'obscur créé il y a 6 mois.
• Poser des questions sur cette chose sans dire quand c'est fait
• ???
• Profit

Comment leur donnez-vous envie d'ajouter de bons commentaires?

D'une expérience avec un collègue que je viens d'avoir. À la fin du projet, nous avons dû rédiger un document récapitulatif de tous les changements apportés au cours du projet. N'ayant pas pris de bonnes notes de validation, mon collègue a estimé que cette tâche prenait beaucoup de temps et a maintenant commencé à faire des commentaires assez longs à chaque validation.

Donc, à emporter, une solution pourrait être que les développeurs écrivent à la fin du projet des documents récapitulatifs détaillant les modifications apportées aux fichiers, les fichiers ajoutés / supprimés et pourquoi.

Proposez ceci à la direction derrière des portes closes:

Le pire des cas se produit: tous les développeurs de niveau supérieur sortent.

Alors que l'entreprise se démène pour occuper des postes de développeur vides, l'équipe de gestion est chargée de communiquer l'état du système au client.

Demandez-leur ce qu’ils pensaient rendre leur travail plus facile pour reconstruire l’histoire de l’application:

Lire des textes en anglais clair décrivant clairement l’évolution de l’état du système?

Ou préféreraient-ils examiner les différences de code et les résoudre eux-mêmes?

Je pense qu'une façon de les convaincre serait de ressentir réellement la douleur que vous ressentez.

Par exemple, supposons qu'ils travaillent sur le problème suivant: Ils ont un bogue apparu lorsqu'une autre correction de bogue pour le même code (oh l'ironie) a été implémentée. Ce serait formidable de pouvoir rechercher ceci en cherchant simplement dans les messages de commit (et ainsi savoir qui l'a écrit).

Une autre façon serait de leur expliquer que le message de validation pourrait être utile pour indiquer pourquoi quelque chose a été mis en œuvre d'une certaine manière. Même si le message de validation ne dit que "fonctionnalité X", vous pouvez toujours obtenir un indice sur son implémentation, de sorte que vous sachiez à qui parler.

Cependant, cela ne semble pas être suffisant pour combattre les deux réponses que je reçois toujours:

1. Cela prend trop de temps et je veux juste que mes modifications soient stockées dans le repo.
2. Il est assez facile de regarder les diffs.

Avez-vous essayé de lancer un défi à vos collègues développeurs afin qu'ils tirent un autre avantage de la formulation de commentaires? On pourrait regarder cela sous deux angles différents:

1. Améliorer leur jeu - Cela peut être la perspective la plus délicate à adopter, mais l’idée ici serait de le faire pendant un certain temps et de s’habituer à l’idée, de sorte que l’habitude est qu’il faudrait plus de temps pour faire l’inverse. Un autre point ici est combien de contrôle les commentaires obtiendraient? Si vous voulez une courte histoire dans le commentaire, je pourrais comprendre leur argument.
2. Subventionner un changement - C’est ici que vous organisez une sorte de concours qui vous permettra d’acquérir le soutien initial nécessaire pour l’essayer ou de proposer un autre type d’incitation à faire effectuer le changement pendant un certain temps.

Autre chose à considérer: savez-vous bien ce que vos collègues développeurs gèrent là où vous travaillez? S'ils essaient de faire 10 choses hier, je pourrais comprendre qu'ils ne veuillent peut-être pas changer ce qu'ils voient comme quelque chose qui fonctionne déjà. Est-ce que vous essayez de leur dire: "Non, ça ne marche pas?" Si c'est le cas, je peux voir en quoi ils peuvent être un peu défensifs ou combatifs. Si vous essayez de leur dire: "Bien que cela puisse fonctionner, il existe une alternative qui pourrait être meilleure ...", alors vous pouvez avoir une chance. Avoir une attitude "Holier que toi" ne va pas vous aider, OMI.

Une autre façon de voir les choses est que les développeurs impliqués développent leur carrière - ils doivent posséder la documentation de leur travail.

Outre les autres points soulevés dans l'article susmentionné, il est possible de réviser les modifications du code pour savoir où / quand / pourquoi une modification a été apportée. Cela pourrait être vital pour dépister un bogue insaisissable.

Une fois que vous les avez convaincus qu'il est important de commenter vos commits, vous pouvez créer un script qui force les commentaires sur les commits, sinon le processus échouera. Vous pouvez même spécifier un minimum de caractères pour garantir un commentaire significatif. Cela les aidera à "se souvenir".

Cependant, il est important qu'ils comprennent le pourquoi, comme l'a dit @ Kevin, sinon ils ajouteront simplement des commentaires aléatoires.

Avez-vous des critiques de code? Une chose qui peut aider est d’instituer une règle selon laquelle tout engagement ou fusion doit être examiné et approuvé par un autre développeur. Ensuite, si vous êtes le relecteur, vous devrez demander au développeur qui s’engage de vous expliquer ce qu’il a fait. Une fois qu'il le fait, vous devriez lui demander de taper dans le commentaire ce qu'il vient de vous dire. Souvent, quand on ne peut pas expliquer de manière cohérente les changements apportés, cela signifie que ces changements n'auraient pas dû être faits en premier lieu.

Je dois dire cependant, comment les gens peuvent-ils s'opposer à quelque chose d'aussi manifestement utile que de faire des commentaires? Cela ne prend pas longtemps du tout et c'est un temps bien dépensé. Ecrire un commentaire vous oblige à réfléchir à ce que vous venez de faire. Cela peut même vous amener à regarder les différences pour vous assurer que vous avez bien fait ce que vous pensez avoir fait et que vous n'avez rien fait de stupide.

Lorsque vous n'écrivez pas les commentaires, vous êtes négligé et indiscipliné. Et si vous insistez pour que vous ne soyez pas obligé d'écrire les commentaires, vous faites délibérément preuve de négligence.

Dites-leur que c'est le seul moyen d'avoir une chance de maintenir votre fouillis procédural de méthodes de 50 000 lignes, puis envisagez d'écrire un code meilleur, plus explicite à l'avenir, afin que vous n'ayez pas à gérer de nombreux commentaires inutiles qui gonflent votre base de code.

Il s’agit d’un élément de changement de processus: demandez à un responsable d’assigner le code développé par "x" à "Y" pour les contrôles d’assurance qualité du code seul, y compris l’assurance qualité des commentaires.

Dans ma propre organisation, les développeurs ne sont pas autorisés à effectuer un contrôle qualité final de leur propre code et à l'archiver, cela doit être effectué par un autre développeur. Une partie de l'AQ Check consiste en des commentaires, donc pas de commentaires, pas de check-in. Nous effectuons beaucoup de travaux à contrat où notre "art" est en réalité la propriété intellectuelle contractuelle de quelqu'un d'autre; les autres doivent donc pouvoir comprendre et exploiter notre code. De plus, il y a des moments où les projets nous reviennent après une longue pause et nous devons être capables de récupérer le code 18-24 mois plus tard et de comprendre le pourquoi, où et comment nous sommes arrivés à l'artefact de code sous nos yeux. Cela fournit une motivation personnelle pour écrire des commentaires de validation.

Demandez à vos collègues développeurs de faire des fusions, de consulter l'historique et de comparer quelques fichiers de l'historique.

Les chances sont qu'ils vous demanderont de mettre des commentaires à partir du lendemain.

Voici quelques conseils:

1. N'essayez pas de changer le monde. Vous allez échouer.
2. Au lieu de cela, vous devriez reconnaître que tout le monde travaille de manière légèrement différente. Aucune taille ne convient à tout le monde.
3. imposer certaines étapes aux processus de travail des gens est très diabolique. Changer ces processus prend 10 ans. Vous leur demandez de le faire avant la prochaine échéance.
4. Même de simples changements de processus peuvent prendre beaucoup de temps.
5. Quelques petits commentaires sur les commits sont bien trop insignifiants pour changer ces processus.
6. Vous pouvez supposer qu'ils font un travail de qualité, mais vous devez leur donner assez de liberté pour choisir les étapes eux-mêmes. Certaines étapes fastidieuses peuvent ne pas être nécessaires pour les développeurs expérimentés.
7. Si vous êtes un babysitting débutant, des processus plus puissants seront peut-être nécessaires, mais les développeurs expérimentés ne doivent pas gérer les conneries.
8. L'imposition de restrictions draconiennes sur la manière dont le travail doit être effectué ne fonctionne jamais, cela ne peut que ralentir les gens (cela peut être bien s'ils sont trop rapides)
9. Beaucoup de gens pensent que leur façon de faire est la seule façon de faire les choses. J'espère que vous n'êtes pas l'un d'entre eux.

Si votre contrôle de code source le permet, activez les commentaires obligatoires pour empêcher tout commmit non commenté. C'est assez simple et tout le monde va bientôt se rendre compte que 5 secondes de frappe d'un commentaire sont indolores.

Mais les commits non commentés sont l’un des plus petits points négatifs. J'ai participé à de nombreux projets réussis pour lesquels aucun commit n'a été commenté. Ne fais pas passer ta culotte dessus.