Y a-t-il un intérêt à 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 la nécessité d'avoir des "journaux des modifications" plâtré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 jonché le code de choses comme:
// 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>
La raison de cela, comme cela m'a été expliqué, est qu'il faut trop de temps pour parcourir nos journaux VCS en essayant de trouver qui a changé quoi et pourquoi, tout en l'ayant dans le fichier de code lui-même, en haut ou près du changement, permet de voir facilement qui a changé quoi et quand. Alors que je vois le point de cela, cela semble redondant et juste une sorte d'odeur de "Eh nous ne comprenons pas vraiment comment utiliser notre VCS correctement, donc nous ne nous embêterons pas du tout avec ça."
Qu'est-ce que tu penses? Utilisez-vous à la fois les commentaires et le journal? Juste le journal? Trouvez-vous qu'il est plus facile de coder lorsque vous pouvez voir ci-dessus un bloc de code que John Smith a changé la méthode pour vérifier XYZ il y a une semaine, au lieu d'avoir à rechercher dans les journaux et à comparer les fichiers de code dans un outil Diff?
EDIT: Utilisation de SVN, mais essentiellement uniquement comme référentiel. Pas de succursales, pas de fusion, rien que le journal + stockage.
J'ai tendance à supprimer les commentaires dans le code. Et par supprimer, je veux dire, avec préjugé . À moins qu'un commentaire n'explique pourquoi une fonction particulière fait quelque chose, elle disparaît. Bye Bye. Ne passez pas go.
Donc, cela ne devrait pas vous surprendre que je supprimerais également ces journaux des modifications, 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 cela vous donne une fausse idée de ce que fait réellement le code.
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 utilisez Subversion, je voudrais souligner qu'il existe de nombreux outils qui vous aideront à gérer votre référentiel Subversion. De la possibilité de naviguer dans votre source à travers le Web, de lier vos ensembles de modifications à des bogues spécifiques, vous pouvez faire beaucoup de choses qui atténuent le besoin de ces "changelogs".
J'ai eu beaucoup de gens commenter et dire que je suis peut-être dans l'erreur de supprimer des commentaires. La grande majorité du code que j'ai vu qui a été commenté était du mauvais code, et les commentaires n'ont fait qu'obscurcir le problème. En fait, si jamais je commente du code, vous pouvez être assuré que je demande pardon au programmeur de maintenance car je suis relativement certain qu'il voudra me tuer.
Mais de peur que vous ne pensiez que je dis que les commentaires doivent être supprimés en plaisantant, cette soumission Daily WTF (à partir d'une base de code sur laquelle j'ai travaillé) illustre parfaitement mon point:
/// 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 sur 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.
Ces "journaux des modifications" intégrés dans le code sont particulièrement naff. Ils apparaissent simplement comme une autre différence lorsque vous différez des révisions, et que vous ne vous souciez pas vraiment. Faites confiance à votre VCS - la plupart ont une fonction "blâme" qui vous montrera très rapidement qui a changé quoi.
Bien sûr, la chose vraiment horrible était cette fonctionnalité des VCS "à l'ancienne" où vous pouviez avoir le journal VCS réel intégré dans les fichiers source. Rendu la fusion presque impossible.
J'ai un seul fichier ChangeLog pour chaque projet qui est automatiquement rempli par certains messages de validation.
Nous n'avons pas de commentaires ChangeLog intégrés. Si nous le faisions, je les retirerais et j'aurais une "conversation" avec la personne qui les ajouterait. Je pense qu'ils sont indicatifs 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 grep des journaux. Nous interdisons également les messages de validation inutiles ou ambigus.
Je déteste personnellement les journaux de modifications dans le fichier source de code. Pour moi, c'est comme si cela violait un principe de génie logiciel en ce sens que tout changement que je fais doit être effectué à plusieurs endroits. Souvent, les informations du journal des modifications sont complètement 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 y a une insistance sur l'implémentation de la pratique de garder un journal des changements dans le code source, le journal des changements devrait être limité aux changements qui affectent l'API/l'interface pulique de la classe. Si vous apportez des modifications au sein de la classe qui ne vont pas casser le code qui l'utilise, l'enregistrement de ces modifications dans un journal des modifications est simplement encombrant à mon avis. Cependant, je peux voir comment il peut parfois être utile de pouvoir vérifier la partie supérieure du fichier de code source pour obtenir de la documentation sur les modifications qui ont pu casser quelque chose pour quelqu'un d'autre. Juste un résumé de la façon dont le changement pourrait avoir un impact sur l'API et pourquoi le changement a été effectué.
D'un autre côté, ma boutique fait principalement des trucs C #, et nous utilisons toujours des commentaires XML en ligne pour documenter notre API, donc la lecture de la documentation sur les changements d'API publics est plus ou moins aussi simple que d'utiliser Intellisense.
Je pense qu'insister sur un journal des modifications dans le fichier source ne fait qu'ajouter des frictions inutiles à 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 en premier lieu.
La dernière entreprise dans laquelle je travaillais avait un logiciel qui avait 17 ans d'histoire, de développement et de mises à jour annuelles. Toutes les migrations d'un système de contrôle de version au suivant 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 la cohérence avec les commentaires/notes d'enregistrement.
Avec des commentaires dans le code source, l'historique archéologique des changements 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 sur 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 sommes tenus de soumettre un commentaire à chaque enregistrement. Non seulement cela, mais nous devons joindre chaque enregistrement avec un billet à Jira. Lorsque vous regarderez Jira à l'avenir, vous pourrez voir tous les fichiers qui ont été archivés et quand pour ce problème, ainsi que le commentaire qui a été laissé. C'est assez pratique.
Fondamentalement, le contrôle de version n'est qu'un outil, c'est la façon dont votre équipe utilise cet outil qui vous fournira les avantages que vous recherchez. Tous les membres de l'équipe doivent s'entendre sur la façon dont ils l'utiliseront pour fournir le meilleur suivi des corrections de bogues ainsi que des révisions de code propres.
Il s'agit d'un reste du temps où les journaux VCS étaient déroutants et les systèmes VCS étaient difficiles à gérer (je me souviens de ces jours, quelque part à l'arrière 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 environ. 30 à 60 minutes pour apprendre à piloter 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 ne se produit 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 il crie "refactor me!".
Nous les incluons toujours dans la source des procédures stockées, car c'est ainsi que nous pouvons 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 comme source aux clients pour la compilation locale dans la base de données.
Notre code PowerBuilder hérité les utilise toujours, mais je pense que c'est juste un facteur de confort pour certains voyants. Cela est également compilé pour la distribution, donc (OMI, ils oughtta) utilisent l'historique VCS friggin.
Si vous utilisez SVN, cela est une perte de temps et totalement inutile.
SVN a la fonction de blâme. Cela vous dira exactement qui a créé chaque ligne dans un fichier donné et quand.
Je suis surpris de voir que personne ne l'a mentionné, mais n'est-ce pas la raison initiale pour laquelle cela est conforme aux exigences de licence? Autrement dit, certaines licences disent que toute modification que vous apportez au fichier doit être notée dans le fichier lui-même?
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 un commentaire, par exemple, selon lequel Fred a rendu le champ Foo requis il y a 6 mois afin de satisfaire une exigence, ce développeur sait qu'il doit poser une question avant d'implémenter la dernière demande pour rendre Foo facultatif. Lorsque vous avez affaire à des systèmes complexes, différentes parties prenantes sont susceptibles d'avoir 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é effectués afin d'éviter des problèmes à l'avenir.
Maintenant, si chaque développeur vérifiait l'historique complet de chaque ligne de code avant de faire un changement, avoir ces commentaires dans le code serait redondant. Mais cela est très irréaliste à la fois du point de vue du flux de travail - la plupart des développeurs changeraient simplement la validation sans rechercher l'historique de qui l'a ajouté et pourquoi - et du point de vue technologique - 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 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 étant 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 peu de code est refactorisé ou lorsqu'un vrai bogue est corrigé. Mais si l'exigence d'origine était "Foo est facultatif" et que quelqu'un arrive et modifie l'exigence en "Foo est requis pour prendre en charge le processus en aval Bar", c'est quelque chose pour lequel j'envisagerais fortement d'ajouter un commentaire. Parce qu'il y a une forte possibilité que certains futurs utilisateurs/analystes ne soient pas au courant du processus de Bar en aval et ignorent la raison pour laquelle Foo a été rendu obligatoire et demanderont de rendre Foo à nouveau facultatif et de causer des maux de tête dans le processus de Bar.
Et cela avant de considérer que les organisations peuvent décider de changer leur système de contrôle de version avec une certaine fréquence, en particulier lorsqu'elles passent de petites entreprises avec une poignée de développeurs à des entreprises beaucoup plus grandes. Ces migrations entraîneront souvent la perte des commentaires du journal des modifications - seuls les commentaires dans le code seront conservés.
La raison pour laquelle nous continuons à maintenir un journal des modifications dans notre section commentaires est pour la facilité d'utilisation. Souvent, lors du débogage d'un problème, il est plus facile de faire défiler vers le haut du fichier et de lire le journal des modifications que d'ouvrir le fichier de contrôle source, de localiser le fichier qu'il contient et de rechercher les modifications apportées