Est-il utile d'inclure un «journal des modifications» dans chaque fichier de code lorsque vous utilisez le contrôle de version?

75

J'avais l'impression qu'un système de contrôle de version éliminait le besoin d'avoir des "journaux de modification" collés partout dans le code. J'ai souvent vu l'utilisation continue des journaux de modifications, y compris de gros blocs longs au début des procédures stockées avec une grande section bloquée pour les modifications du fichier et le code contenant des éléments tels que:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

et:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Comme cela m’a été expliqué, la raison en est qu’il faut trop de temps pour parcourir nos journaux VCS en essayant de trouver qui a changé quoi et pourquoi, tout en le gardant dans le fichier de code lui-même, soit au sommet, soit à proximité du fichier approprié. changer, il est facile de voir qui a changé quoi et quand. Bien que je comprenne le sens de cela, cela semble redondant et nous semble juste un peu "Eh, nous ne comprenons pas vraiment comment utiliser correctement notre VCS, nous ne nous en occuperons donc pas du tout."

Qu'est-ce que tu penses? Utilisez-vous les commentaires et le journal? Juste le journal? Trouvez-vous qu'il est plus facile de coder quand vous pouvez voir ci-dessus un bloc de code que John Smith a changé la méthode pour rechercher XYZ il y a une semaine, au lieu d'avoir à chercher dans les journaux et à comparer les fichiers de code dans un outil Diff?

EDIT: Utilisation de SVN, mais fondamentalement uniquement en tant que référentiel. Pas de branches, pas de fusions, rien sauf log + storage.

version-control coding-standards maintenance Wayne Molina
la source
4
Quel système de contrôle de version utilisez-vous?
ChrisF
11
Certains magasins utilisaient les journaux de modifications avant qu'il y ait des systèmes de contrôle de source. L'inertie et la familiarité gardent les journaux de changement.
Gilbert Le Blanc
2
+1 - Mon équipe fait aussi cela, et j'ai essayé de convaincre certains d'entre eux que c'était le rôle du VCS. Les problèmes commencent lorsque ces commentaires ne sont pas mis à jour avec le code réel ... Et le pire, c'est que la direction a décidé d'ajouter des journaux de modifications à chaque méthode.
Slaphappy
2
+1 - Je me bats avec notre développeur senior depuis presque deux ans à ce sujet. La seule raison pour laquelle il a ajouté ces commentaires inutiles est qu’il facilite un peu la fusion des modifications apportées aux méthodes de 3000 lignes. L’idée qu’une méthode de 3000 lignes est obscène rencontre le mépris.
Joshua Smith
1
Si "cela prend trop de temps pour parcourir vos [journaux] VCS", vous faites quelque chose de mal.
Keith Thompson

Réponses:

46

J'ai tendance à supprimer les commentaires dans le code. Et par supprimer, je veux dire, avec des préjugés . À moins qu'un commentaire explique pourquoi une fonction particulière fait quelque chose, elle disparaît. Bye Bye. Ne passe pas va.

Donc, cela ne devrait pas vous surprendre que je supprimerais aussi ces changelogs, pour la même raison.

Le problème avec le code commenté et les commentaires qui se lisent comme des livres est que vous ne savez pas vraiment à quel point il est pertinent et que cela vous donne une fausse impression de compréhension de ce que le code fait réellement.

Il semble que votre équipe ne dispose pas de bons outils autour de votre système de contrôle de version. Puisque vous avez dit que vous utilisiez Subversion, je voudrais souligner qu’il existe de nombreux outils qui vous aideront à gérer votre référentiel de subversion. Qu'il s'agisse de naviguer sur votre source via le Web, de relier vos ensembles de modifications à des bogues spécifiques, vous pouvez faire beaucoup pour atténuer le besoin de ces 'changelogs'.

Beaucoup de gens ont commenté et ont dit que je me suis peut-être trompé en supprimant des commentaires. La grande majorité du code que j'ai vu qui a été commenté a été un code incorrect et les commentaires n'ont fait qu'obsfucquer le problème. En fait, si je commente un code, vous pouvez être assuré que je demande pardon au programmeur de maintenance, car je suis relativement certain qu'il voudra me tuer.

Mais si vous croyez que je ne dis pas que les commentaires devraient être supprimés par plaisanterie, cette soumission du WTF quotidienne (à partir d'une base de code sur laquelle j'ai travaillé) illustre parfaitement mon propos:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Oh ... Les histoires que je pourrais vous raconter à propos de cette base de code, et je le ferais, sauf qu'elle est toujours utilisée par l'une des plus grandes organisations gouvernementales du monde.

George Stocker
la source
4
Chaque fois que je lutte avec un élément particulier de la logique complexe, les commentaires peuvent parfois m'aider à comprendre le pourquoi de la logique est aussi compliquée. Mais dans l’ensemble je suis d’accord avec vous.
maple_shaft
5
Chaque développeur a au moins quelques mauvaises qualités, je sais que je ne devrais pas mais je ne peux tout simplement pas m'arrêter :) Chaque fois que je crée un TODOcommentaire, un chiot meurt.
maple_shaft
32
Supprimer les commentaires d'autres personnes avec des préjugés contraint en quelque sorte votre propre style de programmation et votre conviction. Les programmeurs débutants et pacifistes n'aboyeront pas, mais vous rencontrez de temps en temps un mâle alpha, puis un combat qui n'aurait pas dû commencer commence. Ainsi, vous avez lu sur un blog intelligent d'une personne intelligente que moins de commentaires, c'est moins. D'autres pourraient ne pas avoir lu le même livre. Même si vous pensez avoir raison parce que quelques personnes sur SO avec un représentant de 5 000 représentants y souscrivent, la dictature n’est pas la solution. J'ai déjà travaillé avec un mâle alpha et j'ai arrêté.
Job
8
@Neil Butterworth: re: ventes: le code se veut malléable. Refacturez-le, changez le, améliorez-le. C'est fait pour ça. Ce n'est pas censé être écrit qu'une seule fois. Notre compréhension des changements commerciaux et lorsque cela se produit, nous devons modifier le code. J'ai beaucoup de problèmes avec les commentaires, mais le plus pertinent pour notre discussion est que les commentaires restent rarement en phase avec le code, et en général ils n'expliquent pas pourquoi quelque chose se passe. Lorsque cela se produit, il est facile de le supprimer. Si quelqu'un vient à moi et demande pourquoi j'ai supprimé le commentaire suivant file.Open() // Open the file. Je ris.
George Stocker
5
Il y a quelques jours, j'ai écrit un morceau de code, un calcul mathématique très complexe, plein de trigonométrie, de transformations, peu importe ... Il m'a fallu environ une heure et demie pour écrire moins de 10 lignes de code. Pratiquement personne autour de moi ne comprend comment cela fonctionne. Je ne comprendrai pas cela dans quelques semaines également. D'autre part, pourquoi c'est là-bas est trivial. Ainsi, au-dessus de ces quelques lignes, se trouve un chapitre entier de texte, expliquant quoi, pas pourquoi. Si vous aviez supprimé ce commentaire, je vous aurais frappé au visage, je me suis fait virer.
Davor Ždralo
76

Les "journaux de modification" incorporés dans le code sont particulièrement dérangeants. Elles se révèlent être une autre différence lorsque vous différez les révisions, et une différence qui ne vous intéresse pas vraiment. Faites confiance à votre VCS - la plupart ont une fonction "blâme" qui vous indiquera très rapidement qui a changé quoi.

Bien sûr, la chose vraiment horrible était cette fonctionnalité des VCS "anciens" où vous pouviez avoir le journal VCS intégré dans les fichiers sources. La fusion est presque impossible.

Neil Butterworth
la source
14
Non seulement ils se révèlent être une différence supplémentaire, mais ils peuvent aussi devenir erronés avec le temps, alors que tout bon VCS sera toujours en mesure de vous dire qui a réellement écrit une ligne particulière, ainsi que l'historique de cette ligne. La seule chose pire que des commentaires inutiles sont des commentaires nuisibles. Ces commentaires commencent comme inutiles et finissent par devenir nuisibles, voire totalement ignorés.
Ben Hocking
10

J'ai un seul fichier ChangeLog pour chaque projet qui est automatiquement rempli par certains messages de validation.

Nous n'avons pas intégré de commentaires ChangeLog. Si nous le faisions, je les enlèverais et je parlerais avec la personne qui les ajouterait. Je pense qu'ils sont révélateurs de ne pas comprendre les outils que vous utilisez, en particulier les vcs.

Nous avons un format pour les messages de validation qui facilite la récupération des journaux. Nous interdisons également les messages de validation inutiles ou ambigus.

dietbuddha
la source
8

Personnellement, j'ai horreur des journaux de modifications au sein du fichier source du code. Pour moi, c'est comme s'il enfreignait un principe de génie logiciel en ce que tout changement que je fais doit être fait à plusieurs endroits. Souvent, les informations du journal des modifications sont totalement inutiles et sans importance. À mon humble avis, les modifications apportées au logiciel doivent être documentées lorsque vous archivez le code.

Mais qu'est ce que je sais...

Je pense que s’il ya une insistance sur la mise en œuvre de la pratique consistant à conserver un journal des modifications dans le code source, celui-ci devrait être limité aux modifications qui affectent l’API / interface pulic de la classe. Si vous effectuez des modifications au sein de la classe qui ne cassent pas le code qui les utilise, l'enregistrement de ces modifications dans un journal des modifications est un fouillis à mon avis. Cependant, je peux voir combien il peut parfois être pratique de pouvoir consulter la partie supérieure du fichier de code source pour trouver de la documentation sur les modifications qui auraient pu causer un problème à quiconque. Juste un résumé de l'impact de la modification sur l'API et de la raison de cette modification.

D'autre part, ma boutique utilise principalement C #, et nous utilisons toujours des commentaires XML en ligne pour documenter notre API. Par conséquent, lire la documentation sur les modifications apportées aux API publiques est plus ou moins simple que d'utiliser intellisense.

Je pense qu'insister sur un journal des modifications dans le fichier source ne fait qu'ajouter un frottement inutile à la machine et va à l'encontre de l'un des objectifs de la mise en œuvre d'un système de contrôle de version.

John Connelly
la source
6

La dernière entreprise dans laquelle je travaillais possédait un logiciel doté de 17 ans d’histoire, de développement et de mises à jour annuelles. Toutes les migrations d’un système de contrôle de version à un autre ne conserveraient pas les commentaires ou les notes d’archivage. Tous les développeurs au cours de ces années n’ont pas non plus maintenu de cohérence avec les commentaires / notes d’enregistrement.

Avec des commentaires dans le code source, l'historique archéologique des modifications a été conservé sous forme de notes, pas de code commenté. Et oui, ils envoient toujours du code VB6.

Tangurena
la source
5

Le contrôle de version peut remplacer les commentaires du journal des modifications dans le code si les développeurs de votre équipe l'utilisent correctement.

Si votre équipe n'ajoute pas de commentaires lors de l'enregistrement, ou laisse des commentaires inutiles, il sera assez difficile de trouver les informations que vous recherchez à l'avenir.

Dans mon entreprise actuelle, nous devons soumettre un commentaire à chaque enregistrement. De plus, nous nous attendons à ce que chaque enregistrement soit accompagné d’un ticket à Jira. À l'avenir, lorsque vous regarderez dans Jira, vous pourrez voir chaque fichier qui a été archivé et quand, pour le problème en question, ainsi que le commentaire laissé. C'est très pratique.

Fondamentalement, le contrôle de version n’est qu’un outil, c’est la façon dont votre équipe utilise cet outil pour obtenir les avantages que vous recherchez. Tous les membres de l'équipe doivent être d'accord sur la manière dont ils vont l'utiliser pour mieux suivre les corrections de bugs, ainsi que les révisions de code propre.

Tyanna
la source
5

Il s'agit d'un reliquat de l'époque où les journaux VCS étaient confus et les systèmes VCS difficiles à gérer (je me souviens de ces jours, quelque part à la fin des années 80).

Votre suspicion est tout à fait correcte, ces commentaires sont plus un obstacle qu’une aide et tout VCS moderne vous permettra de trouver exactement ce que vous recherchez. Bien sûr, vous (et vos collègues) devrez dépenser env. 30 à 60 minutes d’apprentissage de la conduite de toutes ces fonctionnalités (ce qui, je suppose, est en fait la raison pour laquelle ces commentaires sont toujours là).

Je le garde (presque) avec George. Les commentaires dans le code ne sont vraiment justifiés que s'ils expliquent quelque chose qui n'est pas immédiatement visible dans le code lui-même. Et cela n'arrive que rarement dans un bon code. Si vous avez besoin d'avoir beaucoup de commentaires dans votre code, c'est une odeur qui lui est propre et ça crie "refactor moi!".

Wolfgangsz
la source
4

Nous les incluons toujours dans le code source de la procédure stockée, car nous pouvons ainsi savoir exactement quelle version est en place chez un client. Le reste de l'application est distribué compilé. Nous avons donc des numéros de version de module qui renvoient à la source, mais les SP sont distribués en tant que source aux clients pour la compilation locale dans la base de données.

Notre ancien code PowerBuilder les utilise toujours, mais je pense que ce n'est qu'un facteur de confort pour certains peeps. Cela est également compilé pour la distribution, donc (IMO ils oughtta) utilisent l'historique de VCS.

DaveE
la source
1
+1 J'allais écrire cette réponse mais tu m'as épargné le problème. Non seulement les procédures stockées sont distribuées en tant que source, mais également de nombreux langages de script. J'utilise beaucoup OpenACS et TCL - souvent, si un client dispose d'une version fourchue d'un fichier particulier, le seul moyen de s'assurer que vous connaissez sa version est en lisant le journal des modifications. Particulièrement pratique si vous êtes connecté au site d'un client et que vous ne parvenez pas facilement à faire des différences avec le logiciel de contrôle de version.
Nom de Trojan
3

Si vous utilisez SVN, le faire est une perte de temps et est totalement inutile.

SVN a la fonction de blâme. Cela vous dira exactement qui a fait chaque ligne dans un fichier donné, et quand.

comment s'appelle-t-il
la source
1

Les commentaires du journal des modifications sont exceptionnellement utiles dans le code lorsqu'ils aident un développeur ultérieur à poser de meilleures questions concernant les nouvelles exigences. Lorsqu'un développeur voit, par exemple, un commentaire que Fred a rendu obligatoire sur le champ Foo il y a 6 mois afin de satisfaire certaines exigences, il sait qu'il doit poser une question avant de mettre en œuvre la dernière requête pour rendre Foo facultatif. Lorsqu'il s'agit de systèmes complexes, différentes parties prenantes ont probablement des priorités et des désirs différents. Les commentaires du journal des modifications peuvent être très utiles pour documenter lesquels de ces compromis ont été faits pour éviter des problèmes à l'avenir.

Désormais, si chaque développeur vérifiait l'historique complet de chaque ligne de code avant d'apporter des modifications, la présence de ces commentaires dans le code serait redondante. Mais ceci est très irréaliste à la fois du point de vue du flux de travail - la plupart des développeurs ne feraient que modifier la validation sans rechercher l'historique de qui l'a ajouté et pourquoi - et du point de vue de la technologie - un système de contrôle de version aurait du mal à suivre le même "ligne de code si elle est passée d'une ligne à une autre ou si elle a été refactorisée dans une classe différente. Les commentaires dans le code sont beaucoup plus susceptibles d'être vus et, plus important encore, d'inciter un développeur ultérieur à noter qu'un changement apparemment simple peut ne pas être aussi simple.

Cela dit, les commentaires du journal des modifications dans le code devraient être relativement rares. Je ne préconise pas que les commentaires du journal des modifications soient ajoutés chaque fois qu'un code est refactoré ou lorsqu'un vrai bogue est corrigé. Mais si l'exigence d'origine était "Foo est facultatif" et que quelqu'un se présente et remplace l'exigence par "Foo est nécessaire pour prendre en charge le processus en aval", c'est quelque chose pour lequel j'envisagerais fortement d'ajouter un commentaire. Parce qu'il est fort possible qu'un futur utilisateur / analyste ne soit pas au courant du processus du barreau en aval ni de la raison pour laquelle Foo a été rendu obligatoire, il demandera à nouveau de rendre Foo facultatif et de causer des problèmes dans le processus du barreau.

Et ceci avant d’envisager que les entreprises puissent décider de modifier leur système de contrôle de version assez fréquemment, en particulier à mesure qu’elles évoluent de petites entreprises avec une poignée de développeurs à des entreprises beaucoup plus grandes. Ces migrations entraînent souvent la perte de commentaires dans le journal des modifications. Seuls les commentaires dans le code seraient préservés.

Justin Cave
la source
Existe-t-il des conversions VCS qui ne conservent pas les messages de validation?
David Thornley
1
@ David - J'ai vu beaucoup de choses qui n'en ont pas. Je ne sais pas s'il y avait des obstacles techniques à le faire ou si quelqu'un a décidé qu'il était plus facile de "tout recommencer à zéro" et d'enregistrer tout le code dans le nouveau VCS le premier jour.
Justin Cave le
l'ajout d'un commentaire expliquant pourquoi un processus a changé peut être utile, et parfois l'ajout d'un commentaire expliquant quand il a changé, mais je ne vois pas l'intérêt de mettre ce commentaire sous la forme d'un journal des modifications. D'une part, cela masque quelque peu l'utilité du commentaire ("Oh, c'est juste un commentaire du journal des modifications"), et deuxièmement, cela encourage d'autres commentaires inutiles dans le journal des modifications (renforcement # 1).
Ben Hocking
Cesser d'utiliser Visual Source Safe? Tous les systèmes de contrôle de code source modernes utiles gèrent correctement les journaux de modifications. Nous le savons par définition car s'ils ne le savaient pas, ils ne seraient pas considérés comme utiles. Si vous passez 30 minutes à apprendre à utiliser le contrôle de source que vous avez, cela vous rendra beaucoup plus efficace que simplement prier quelqu'un qui connaît vos outils, vous épargnera des miettes. Sans parler du fait que l’historique du code n’est pas souvent pertinent, vous ne faites que tester et écrire maintenant, maintenant.
ebyrob
En ce qui concerne le "changement de contrôle de code source" - presque tous les systèmes modernes peuvent déplacer l’historique les uns contre les autres, générer des fichiers de changements individuels au niveau du projet, ou bien intégrer leurs journaux de changements dans le fichier source (dès que pas avant). La technologie est donc là, le problème réside dans le choix des utilisateurs de ne pas utiliser correctement le contrôle de source.
ebyrob
1

Je suis surpris de voir que personne ne l'a mentionné, mais la raison initiale de cela n'est-elle pas de se conformer aux exigences de licence? C’est-à-dire que certaines licences indiquent que toute modification apportée au fichier doit être notée dans le fichier lui-même?

Sverre Rabbelier
la source
1
quelles licences disent ça?
Trasplazio Garzuglio
2
J'ai travaillé à un endroit où la conformité à la loi Sarbanes Oxley, à laquelle ils croyaient, exigeait des blocs de modifications dans les fichiers source. Ils ont également utilisé PVCS (alias "Dimensions") au fil des années, ils n'avaient donc aucun contrôle de version, mais que savais-je?
Bruce Ediger
@Marco: Je ne me souviens pas ou j'aurais lié à cela.
Sverre Rabbelier le
1
La section 2a de la GPLv2 l'exige. La plupart des projets l'ignorent, certains n'ont qu'un seul fichier "ChangeLog" (souvent généré à partir de leur VCS).
jeudi
0

La raison pour laquelle nous continuons à tenir à jour un journal des modifications dans notre section de commentaires est la simplicité d'utilisation. Lors du débogage d'un problème, il est souvent plus facile de faire défiler le fichier jusqu'en haut et de lire le journal des modifications plutôt que d'ouvrir le fichier de contrôle source, de localiser le fichier dans celui-ci et de rechercher les modifications apportées.

briddums
la source
1
Personnellement, je trouve un peu pénible qu’un fichier de 200 lignes atteigne 1 000 lignes en raison de l’ajout d’un journal des modifications dans chaque fichier source. Ce bruit supplémentaire masque en fait ce qui est important avant longtemps.
ebyrob