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

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.

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.

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.

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.

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.

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.

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.

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!".

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.

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.

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.

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?

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.