Pourquoi devrais-je écrire un message de validation?

Pourquoi devrais-je écrire un message de validation? Je ne veux pas et je pense que c'est stupide à chaque fois.

Une interface graphique que j'utilise et qui ne portera pas de nom vous oblige à le faire. J'entends d'autres le faire à chaque fois, même s'ils utilisent le VCS sur la ligne de commande.

Si je m'engage plusieurs fois par jour et que je n'ai pas terminé une fonctionnalité, de quoi suis-je en train d'écrire? J'écris UNIQUEMENT un message après de nombreuses validations et je pense qu'il est temps pour une mini-balise ou quand je fais une vraie balise.

Ai-je raison ou ai-je raté quelque chose? aussi j'utilise un système distribué

À toutes les personnes qui disent "n'engagez que lorsque vous avez un message utile et bien pensé à écrire, et lorsque votre fonctionnalité est terminée à 100% et que vous avez des tests unitaires", je dis: vous êtes toujours dans l'état d'esprit SVN .

Si vous utilisez git , voici ce que j'appellerais un flux de travail intelligent:

1. Engagez-vous aussi souvent que vous le souhaitez . Écrivez-y tout ancien message rapide. Personne ne le verra de toute façon.
2. Après avoir dit, 10 commits, vous avez terminé cette fonctionnalité sur laquelle vous travailliez. Maintenant, écrivez des tests et validez ces tests. Ou tout ce que vous voulez d'autre. Si vous aimez TDD, écrivez d'abord des tests, je m'en fiche, ni git.
3. git rebase -ià partir du premier commit "salissant", vous avez ajouté et corrigé votre historique local en écrasant, éditant, omettant et autrement nettoyant votre historique récent en commits logiques et propres avec de beaux messages .
4. Après le nettoyage, demandez à quelqu'un de vous retirer.
5. Rincez et répétez.

Notez que l'étape 3 se produit lorsque vous vous retrouvez avec les bons commits que vous recherchiez, et qu'en utilisant SVN, vous devez vous abstenir de vous engager jusqu'à ce que vous ayez effectué les deux premières étapes, ce que suggèrent la plupart des autres réponses. IOW, vous ne voulez pas infliger votre code à moitié écrit et non testé aux autres, donc vous ne vous engagez pas pendant une semaine, jusqu'à ce que votre fonctionnalité soit terminée. Vous n'utilisez pas le contrôle de version à son plein potentiel.

Notez également que n'importe où entre les étapes 1 et 3, vous pouvez git pushapporter vos modifications à votre propre miroir de dépôt privé sur le serveur pour obtenir des sauvegardes gratuites si le disque dur de votre ordinateur portable meurt.

Parce que quand un mauvais mainteneur chasse un bug et trouve qu'il a été ajouté en rév. xyz, il voudra savoir ce que rev. xyz était censé faire.

Vous commentez votre code source, non?

Vous écrivez les meilleurs commentaires, ceux qui disent pourquoi car le code dit seulement comment ?

Le message de validation est un tel commentaire, et donc il est très important et plus vous y réfléchissez, plus il est utile à un futur mainteneur du logiciel.

Pour tout logiciel actif, ce commentaire particulier finira par être affiché dans quelque chose comme

(trouvé à http://longair.net/blog/2009/04/25/a-few-git-tips/ ). Cela permet d'avoir une vue à vol d'oiseau de qui a travaillé sur le logiciel quand et de ce qu'il a fait.

Notez que c'est le but ultime pour le commettras commentaire, à savoir montrer dans une telle liste en disant « ce que » à votre moi futur ou votre collègue, et qui est la raison pour laquelle vous devez prendre soin par écrit des messages bon engagement.

Si le message de validation vous semble stupide, il semble que vous n'utilisiez pas correctement les validations.

Les validations doivent être effectuées pour une bonne raison - elles doivent être liées aux tâches que vous avez décomposées pour la fonctionnalité sur laquelle vous travaillez. Que ces tâches soient formelles ou simplement dans votre esprit, chaque changement que vous effectuez devrait plus ou moins terminer une tâche et donc être fonctionnel d'une manière ou d'une autre.

Vos messages de validation servent alors un bien meilleur objectif. Décrivez la tâche que vous avez terminée et si elle n'est pas suivie ailleurs, pourquoi cette tâche était nécessaire ou à quoi elle sert:

• Refonte de la classe d'utilisateurs pour une meilleure encapsulation
• Stubs API créés pour que les interfaces puissent être utilisées dans la classe de contrôleur
• Conversion de la classe de base de données en classe abstraite afin qu'une base de données fictive puisse être utilisée dans les cas de test

Ensuite, vous ou d'autres développeurs pouvez parcourir l'historique du référentiel ou du fichier et voir assez facilement où certaines évolutions se sont produites et pourquoi. Ou, si une révision particulière se révèle coupable d'un bogue, le message de validation donnera un indice sur la raison pour laquelle cette ligne a été insérée, de sorte que vous ne vous contentez pas de la déchirer et que vous puissiez éventuellement casser à nouveau quelque chose que l'on pensait être fixe, et vous pouvez le corriger de la bonne façon.

Les commentaires de validation ne résolvent pas tout. Il y a toujours une chance qu'ils induisent en erreur autant qu'ils aident - en particulier lorsque les développeurs sont en colère de devoir les saisir. Essayez ceci: considérez-les comme une piste de chapelure dans les bois ou un waypoint d'alpinisme ou des balles de traçage. Bien faits, ils peuvent tracer un chemin autrement déroutant.

N'en faites pas grand cas. Être honnête:

• "Entités indexées spatiales modifiées, Daos et interfaces utilisateur pour gérer la fonction X"
• "Enregistrement incrémentiel pour la demande de fonctionnalité # 1234 et le bogue # 5678"
• "J'ai cassé la dernière version. Ce sont les fichiers qui m'ont manqué."

Soyez bref et "une vue d'ensemble". Si possible, reportez-vous à un numéro de problème dans votre système de fonctionnalités / bogues. Certaines interfaces utilisateur de contrôle de version incluent un champ pour ce genre de chose.

Il réduit le nombre de WTF / minute;)

ce qui se traduit par une équipe plus heureuse (qui ne vous déteste pas) et une meilleure sortie d'équipe potentiellement à moindre coût

Ainsi, le reste de votre équipe sait que WTF vous archivez les modifications apportées à l'arborescence du projet.

parce que si vous ne vous entraînez pas à entrer des messages de validation décents, vous finirez comme mon collègue qui saisit des messages comme

no changes

ou

testing

pour les commits avec plus d'une centaine de fichiers modifiés (sans blague ici !!).

Si vous devenez un tel développeur, vous aurez l'air stupide aux yeux du reste du monde, peu importe à quel point vous pensez que c'est stupide de simplement entrer un message.

Pourquoi vous engagez-vous si les changements ne sont pas significatifs?

Validez simplement les changements qui ont un sens. Par exemple, j'ai fait un refactoring plutôt important l'autre semaine, ce qui m'a pris environ 3 jours. J'aurais des tonnes de commits pendant ce temps. Certains étaient des changements plutôt modestes («renommé la classe X en Y pour refléter une nouvelle responsabilité» ou «déplacé la méthode Z () vers la classe Q») et d'autres étaient vraiment importants. Quand j'ai fini avec une fonctionnalité / refactoring, je vérifie si certaines validations peuvent être écrasées (au moins git le supporte, je ne sais pas pour les autres outils), mais généralement je les laisse telles quelles car cela aide plus tard.

Je suppose que vous ne vous engagez pas au milieu de l'édition d'une ligne, donc elle devrait avoir un sens. Décrivez simplement ce que vous avez fait depuis le dernier commit.

imaginez une condition lorsque vous avez cassé votre système en effectuant des changements et réalisez-le après plusieurs validations par l'équipe. Vous ne vous souvenez pas de la modification, mais vous vous souvenez que quelque chose pourrait mal se passer lorsque vous amélioriez la fonctionnalité X ou supprimiez un fichier du module Y.

Mais malheureusement, le numéro de révision ne vous dit pas quand vous avez changé X ou Y. Donc, votre choix est de lire tous les codes validés au cours des N derniers jours ou simplement de lire les messages de validation détaillés que vous avez écrits (beaucoup plus lisibles que le code).

Donc, si vous écrivez le même, le texte ennuyeux, inutile et non lié dans le message de validation, parce que vous le devez, est plus dangereux que d'avoir un message de validation. Parce qu'au lieu de trouver la racine du bug, un mauvais message vous induira en erreur.

Essayez donc d'écrire des messages de validation significatifs à chaque fois que vous vous engagez, ce qui peut vous aider ainsi que le responsable.

Si vous travaillez avec d'autres, les messages de validation sont très importants pour voir ce que les autres ont fait: rechercher les différences pour chacun d'eux est beaucoup plus de travail et vous pourriez ne pas comprendre pourquoi quelqu'un l'a fait. Si vous travaillez avec d'autres personnes et que quelqu'un (peut-être pas vous) doit réellement regarder en arrière, par exemple pour suivre comment le comportement a changé depuis la version précédente de manière inattendue ... vous rendez vraiment la vie difficile en n'utilisant pas un indice utile dans la validation message.

Si vous travaillez seul ... sur un projet qui est principalement codé "tel quel" (par exemple, un simple site Web ou script), je peux plus ou moins voir d'où vous venez. Si je travaille sur quelque chose comme ça, je ne me soucie que de la date / heure ou des changements les plus récents lorsque je continue de travailler sur quelque chose (vous avez un point à restaurer, mais cela n'a d'importance que pendant le développement, pas après l'avoir implémenté). Le contrôle de version n'est qu'un moyen de faire des sauvegardes avec quelques avantages - je suis entièrement d'accord pour dire que ce n'est pas une utilisation complète du système - mais sur certains projets à petite échelle, cela pourrait ne pas être nécessaire.

L'idée m'est venue à l'esprit avant que le contrôle de version soit utilisé de deux manières, l'une pour documenter les changements dans le projet et l'autre pour aider les développeurs en place ... et ces deux sont totalement différents l'un de l'autre. Les messages de validation sont très importants dans un sens et peuvent être pour la plupart inutiles dans l'autre.

Vous manquez quelque chose. Il doit y avoir une raison pour effectuer un commit sinon vous ne le feriez pas.

Tout ce que vous devez faire dans le commentaire est de mettre la raison en mots, même si ce n'est que wip: adding new state objects

Comme beaucoup d'autres, je fais un peu de codage pendant mon temps libre et j'utilise un système de contrôle de révision pour suivre à la fois mon développement et mes changements. Le temps libre dont je dispose varie considérablement d'une semaine à l'autre et d'un mois à l'autre. Il y a eu beaucoup d'occasions où je n'avais pas le temps de coder sur un projet pendant des semaines, voire des mois, et le temps que j'avais variait généralement de 10 minutes (journée typique) à 40 minutes (bonne journée). Ces conditions ne sont certainement pas excellentes - en particulier pour les problèmes de débogage.

Il était essentiel de conserver des notes qui ne se perdraient pas et seraient facilement récupérables. À la fin de chaque session, le travail de la session serait engagé avec un message détaillé. Je pourrais ensuite parcourir l'historique des validations et suivre mes progrès et mon processus de réflexion. Cela m'a permis de reprendre où j'étais la semaine dernière, ou le mois dernier avec le moins de temps précieux perdu.

Le point que j'essaie d'illustrer est que de bons messages de validation vous aident (ainsi que toute autre personne qui vient après vous) à comprendre ce qui s'est passé, ce qui s'est passé, où les choses vont et surtout pourquoi.

Pensez-y logiquement pendant une minute. Lorsque vous vous engagez, cela signifie que quelque chose a été fait. Si vous ne laissez aucun message, comment les autres sauront-ils ce qui a été fait?

Si vous ne commentez pas vos commits, vous pourriez être tenté de commenter le changement dans la source. Avec le temps, cela peut encombrer la source.

Les messages de validation sont un moyen rapide de savoir ce qui se passe dans cet enregistrement et aideront les autres développeurs de votre équipe lorsqu'ils veulent savoir quel aspect du code a changé dans quelles révisions (pour diverses raisons).

Sur une note connexe, je suggère de spécifier le numéro de cas du suivi des bogues (j'espère que vous en utilisez un) dans le message de validation, afin qu'il soit utile pour l'avenir de suivre facilement les choses.

Pour que le responsable de ce code 1 an plus tard sache qui traquer ce code atroce. :)