Pourquoi devrais-je écrire un message de validation?

18

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é

2528
la source
1
Ne vous embêtez pas, dites simplement "bla" dans la ligne de commentaire. Tant que vous ne partagez jamais le code avec quelqu'un d'autre et aussi longtemps que personne ne travaillera dessus et tant que vous n'aurez jamais besoin de restaurer le code et tant que vous ne ferez jamais une seule erreur de code et ... attendez une minute, pourquoi utilisez-vous à nouveau le contrôle de version?
Michael Durrant

Réponses:

24

À 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.

Alex Budovski
la source
Bonne réponse, j'aime ça. J'ai un peu peur d'utiliser rebase. Voici un article sur le problème et comment le récupérer bluemangolearning.com/blog/2009/03/…
@acid, si vous rebasez vos propres modifications privées, il ne devrait pas y avoir de conflits. De plus, vous devez essayer dur de perdre quoi que ce soit dans git.
Alex Budovski
4
mon flux de travail, git rocks
Nazgob
1
@Boris: Parce qu'il parle clairement de git qui n'est clairement PAS une subversion
3
Cela ne devrait vraiment pas être un travail important d'écrire une phrase indiquant ce que vous venez de faire, et détruire l'histoire avec rebase semble désagréable. Supposons que vous ayez introduit un bug dans le 5e de ces dix commits qui n'est détecté qu'une semaine plus tard. Être capable de l'épingler à un seul petit commit vous aidera beaucoup.
Gort le robot
55

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.

Peter Taylor
la source
38
Eh bien, il peut lire les 5 000 lignes de spaghettis que je viens de vérifier, JEESH !!! Certaines personnes sont juste paresseuses!
Edward Strange
9
Parce que lorsque le pauvre meunier vous suivra (dans 3 ans) et regardera l'histoire et s'en ira ... WTF .. WTF .. WTF, il aura au moins une idée de ce qui se passait. Vous pouvez facilement ajouter un commentaire comme "enregistrement de routine, fonctionnalité X, incomplet".
quick_now
3
@ acidzombie24: Parce que chaque commit doit dire à quoi il sert - même s'il s'agit d'une "faute de frappe corrigée ....", il n'y a aucun intérêt dans un historique de révision, à moins que vous ne sachiez à quoi servent les révisions.
Orbling
11
@quickly_now, le pauvre meunier pourrait même être vous-même. Malheureusement, c'est l'une des choses que vous devez vivre vous-même pour l'apprécier pleinement.
2
@acidzombie - pourquoi enregistrez-vous des modifications incomplètes ??
Edward Strange
35

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

gitk - tous les échantillons

(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.

utilisateur1249
la source
2
@acidzombie, je ne peux parler que pour git, mais vous pouvez vous engager en très petites étapes localement, puis les regrouper en un seul commit lorsque vous poussez en amont. Ce message de validation peut alors être descriptif.
2
@acidzombie, pourquoi vous engagez-vous si vous n'avez pas fait suffisamment de changements pour justifier un commentaire? S'il vous plaît, expliquez.
2
@Thor: Parce que le contrôle de version protège votre code contre la perte, et même le code à moitié fait doit être protégé.
Ben Voigt
1
@Ben, les validations sont destinées au stockage à long terme et doivent refléter avec précision les «morceaux» de travail. La protection contre la perte est à mon avis orthogonale au contrôle de version et doit être gérée par un système de sauvegarde approprié. J'ai trouvé Time Machine pour Mac extrêmement bien adapté à cet effet - j'espère qu'un système similaire est disponible pour Windows.
2
+1 Je suis fan de ne pas polluer mon contrôle de source avec des commits sans signification. Cela facilite la recherche d'un commit particulier (grâce à des commentaires utiles), et je sais que lorsque je récupère du code, il est toujours en état de marche. Le logiciel de sauvegarde traditionnel est une meilleure option pour protéger mon dépôt local entre les validations. Cela fonctionne bien avec un DVCS, mais vous devez vous rappeler qu'un enregistrement local n'est pas vraiment une sauvegarde de votre code.
Adam Lear
15

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.

NickC
la source
1
+1, on dirait qu'il s'engage trop fréquemment ou à de mauvais points d'arrêt. S'il veut juste un bon point de sauvegarde pour certains changements expérimentaux, il peut utiliser l'index, une branche temporaire, modifier les validations précédentes au lieu d'en créer de nouvelles, ou même utiliser le tampon d'annulation dans son éditeur.
Karl Bielefeldt
1
@Karl: Le linus de l'IIRC dans son discours sur Google Git a déclaré qu'en moyenne 6 commits sont effectués par jour. Maintenant, je ne sais pas combien est considéré comme beaucoup, mais sur ce projet en ce moment, je me suis engagé quand j'ai fait travailler la réflexion (je boucle les bonnes données, je ne fais rien avec), après avoir généré l'interface mais avant que la sérialisation ne fonctionne. et je travaille maintenant à faire fonctionner la sérialisation même si j'avais l'interface il y a 2 heures. Je vais valider et dire 'réflexion de base' une fois que cela fonctionne, mais sur les trois premiers pourquoi devrais-je jamais laisser un commentaire quand je peux facilement voir quand une fonctionnalité `` fonctionne '' chaque x est validé.
En fait, je peux attendre jusqu'à ce que j'obtienne un test de base car sinon, si je commente chaque commit, comment saurais-je lequel a une réflexion stable? 'réflexion de base', 'sérialisation par réflexion' 'test de sérialisation par réflexion' En supposant que la sérialisation est un must, il peut s'agir du 2e ou du 3e. Test pourrait signifier test unitaire ou test peut signifier test si son travail sur les classes de base dont j'ai besoin. Je pense simplement que commenter est logique lorsque je peux dire «réflexion de base» plutôt que de deviner lequel de ces principes signifie que les principes de base fonctionnent. Il est également plus facile de parcourir / trouver quand il y a moins à lire.
@acid, le but d'un commit est de pouvoir y revenir ou comparer les modifications avec lui. Si vous avez besoin de le faire avec vos commits précédents, comment savez-vous lequel choisir? Vous n'êtes pas obligé d'écrire des romans, ici. "interface de travail", "sérialisation de travail" et "réflexion de travail" sont très bien à mon avis. Il n'y a pas de nombre maximal de validations par jour, mais si vos messages se lisent comme "un peu de travail sur l'interface" "un peu plus de travail sur l'interface" "une interface presque terminée", alors vous vous engagez trop souvent et devez simplement utiliser l'index.
Karl Bielefeldt
@Karl: Quel est l'indice btw? je sais que git a une cachette mais je ne pense pas que vous en parliez. Qu'est ce que ça fait?
12

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.

Scant Roger
la source
2
+1 pour l'idée de rester court. Court et simple et assez bon est parfaitement bien.
quick_now
1
À mon humble avis, une recette encore meilleure serait la recette commune "aussi courte que possible, aussi longtemps que nécessaire"; car parfois il n'est tout simplement pas possible de rester court sans sacrifier les informations essentielles
hvr
11

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

entrez la description de l'image ici

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

Tour
la source
4
Je voterais pour cela si vous expliquiez pourquoi cela est vrai.
SingleNegationElimination
@TokenMacGuy - Désolé, je ne suis pas abonné.
Tour le
1
Comment les messages de validation expressifs réduisent-ils les WTF / minutes (ils le font, certainement)
SingleNegationElimination
@TokenMacGuy - Je pensais que c'était évident.
Rook
9

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

Edward Strange
la source
7
J'ajoute des messages de commit pour mes projets, quand je suis le SEUL DÉVELOPPEUR! Parce que quand je reviens dans 2 ans pour regarder ces trucs, je veux savoir le WTF que je faisais à l'époque. Je sais parfaitement que 99% du temps cela ne sera pas examiné. Le 1% du temps, cela me fera économiser 2 semaines d'agonie, et je pense que le prix de la saisie d'un message de validation de 10 secondes vaut le bénéfice à long terme que j'obtiendrai.
quick_now
@quickly_now, agonie même? Votre code est-il si mauvais?
1
@quickly_now: Amen à cela. En l'espace d'un an ou deux, beaucoup de code sort de moi, ce que chaque petit bout était censé faire des mois plus tard, Dieu seul le sait. Dieu, et mon histoire de révision.
Orbling
Oh oui. Je suis d'accord aussi. Je pense à cela comme expérience == humilité.
Michael Durrant
8

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.

stijn
la source
1
sonne comme un candidat parfait pour l'examen par les pairs avant de s'engager, si j'en ai jamais entendu un.
2
oh mec, j'ai travaillé avec ce genre de personnes. Ça me rend fou.
sevenseacat
4

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.

EricSchaefer
la source
3

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.

GG01
la source
Pourquoi devrais-je le faire à chaque validation plutôt qu'à la fin de la journée, tous les deux jours ou lorsque je termine une fonctionnalité?
1
pourquoi vous engagez-vous si souvent, si cela n'a pas de raison "naturelle"?
Je m'engage chaque fois que j'apporte des modifications importantes, afin qu'elles puissent se refléter dans le référentiel et que d'autres développeurs puissent vérifier ces modifications. Mais la réponse que vous lui avez donnée aide à avoir un œil d'oiseau sur ce qui est fait par qui et quand.
GG01
@ acidzombie24 Eh bien, ne commettez pas de choses à moitié terminées, sauf si vous y êtes vraiment obligé. Et ainsi les autres personnes peuvent voir ce que vous faites / travaillez lorsque vous appelez un jour un malade et que rien ne fonctionne. Ou alors, vous vous souvenez où vous vous êtes arrêté lorsque vous devez vous asseoir en réunion pendant 2 jours. Ou alors vous identifiez plus facilement quelle révision a cassé une construction et regardez le diff.
nos
@ Thorbjørn: Pourquoi ne commettrais-je pas un changement que je ne veux pas refaire?
3

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.

Inca
la source
3

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

Richard Harrison
la source
exactement. Même si (comme mentionné précédemment) c'est juste du code que vous ne voulez pas refaire bien évidemment, cela signifie quelque chose donc il ne devrait pas être difficile d'en écrire un résumé ultra-rapide.
sevenseacat
2

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.

Sparky
la source
2

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?

Sergio
la source
Un coup d'œil à mon code incroyablement évident et ils sauront instantanément tout ce qu'il fait et tous les tests incroyables qu'il réussit à 100%. Désolé, je suis d'humeur d'humour ce soir [donc je plaisante];)
Michael Durrant
1

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.

Joris Geer
la source
2
je ne suis pas tenté de le faire
1

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.

Mahesh Velaga
la source
1

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

talonx
la source
C'est à cela que blamesert la fonction du vcs.
Peter Taylor