Certains des développeurs du projet que je travaille ont l'habitude de commenter leur code pour montrer quelle version du produit à ajouter, par exemple chaque fois que je vois que mon sang La pression augmente et je dois passer 5 minutes à naviguer pour vous rafraîchir. Il me semble qu'ils ne comprennent pas le contrôle de la version et si je devais utiliser cette pratique, toutes les autres lignes dans les fichiers source seraient un commentaire sur quand les choses ont été ajoutées. J'envisage de supprimer tous ces commentaires des fichiers que je travaille, mais je me demande est-ce que je suis juste difficile et y a-t-il une certaine valeur pour ces commentaires?
11 Réponses :
Considérez que certains peuvent avoir à attraper des instantanés de la VCS. Dans ce cas, ils n'ont pas d'antécédents à revenir. Et de tels commentaires deviennent utiles.
Quand j'ai rejoint la première fois à ma société (il y a plus de 10 ans), ils utilisaient un système de contrôle source de la maison qui n'avait aucune information sur l'histoire. Ils ont dû utiliser des commentaires pour montrer pourquoi les choses ont changé et cette habitude était difficile à briser. Je suis heureux de dire que nous utilisons maintenant Subversion et même rechercher activement ces commentaires et les supprimer de la base de code.
Pourquoi quelqu'un attrape-t-il des instantanés? Ils devraient faire une branche ou une migration?
Si vous utilisez le contrôle de la source, je préconiserais ajouter une étiquette de construction au contrôle de la source après chaque construction. De cette façon, vous pouvez rechercher toutes les sources modifiées pour une construction spécifique, sans aucun commentaire méchant, encrassant votre code.
Ceci du code de nettoyage, un livre de Bob Martin:
"L'utilisation correcte des commentaires est de compenser notre défaut d'exprimer nous-mêmes en code. Notez que j'ai utilisé le échec du mot. C'est ce que je voulais dire. Les commentaires sont toujours échecs. "
Je pense toujours à cette citation quand je vois un commentaire, je ne suis donc pas surpris que tes furoncles de sang.
@Nickgps: "Les commentaires sont toujours des échecs" est une ligne assez difficile - je traiterais cela comme une aspiration plutôt qu'une règle! Cependant, je suis d'accord à 100% que le contrôle de la source est la réponse à cela, pas des commentaires.
Pas de valeur que ce soit. Si vous avez un outil de blâme dans votre contrôle de version, cela y réalisera, ils ajoutent simplement du bruit.
Ce qui est pire, c'est qu'ils attireront d'autres commentaires sur votre code pour le rendre complètement illisible p> et que quelqu'un supprimera la méthode mais laissez le code de code dans p > // added for superEnterpriseyWonder v2.5
// bug fix #12345674 should have been true
// v2.6 now need to up the counter DO NOT DELETE
// end added for superEnterpriseyWonder v2.5
Votre code modifié a l'air très proche de certains du code ancien qui se trouve dans le système (plus de 10 ans de Cruft).
J'ai vu que beaucoup dans le code écrit par des personnes qui n'ont pas utilisé de contrôle de version avant récemment. Je suppose qu'ils ont juste pris l'habitude et maintenant il est difficile de s'arrêter.
Une autre raison que j'ai trouvée était que, parfois, il est important de savoir quel élément de code est associé à quelle version. Bien sûr, vous pouvez toujours vérifier le journal de la version, mais vous n'avez pas toujours du temps pour cela, et c'est ennuyeux. Dans certains cas, dire "Code pour V3.2" parle davantage à d'autres développeurs que "code pour faire x, y et z" ... Tout dépend des conventions établies par l'équipe.
Une autre réponse est que, dans certains projets, j'ai travaillé avec un certain code a été commenté comme ça, mais c'était avant que le projet ait commencé à utiliser la version de la version. Dans ce cas, il était également logique de le garder de cette façon.
Je dirais qu'il n'y a pas de valeur: cette information peut également être récupérée avec la fonctionnalité d'annotation / blâme de votre SCM. En outre, tout le monde peut ajouter du texte entre ces commentaires, qui rendent les commentaires datés (puisque vous pouvez ajouter quelque chose pour V2.6 pendant que les commentaires disent V2.5)
Une autre chose à noter est que ces commentaires sont essentiellement cachés: vous ne les voyez que lorsque vous examinez le code source en question, vous ne pouvez donc pas l'utiliser pour générer un changelog ou quelque chose.
pourrait être utile dans certains cas (par exemple, si cela aide à comprendre pourquoi une fonction fonctionne différemment en V3 que dans V2) mais en général, c'est le travail de la SCM de savoir ce qui a été ajouté quand.
Le commentaire comme indiqué, n'est probablement pas utile. Cependant, il peut y avoir des moments où l'ajout d'une fonctionnalité peut entraîner l'ajout de code non évident. Dans ce cas, un commentaire décrivant le changement et / ou pourquoi le code n'est pas évident serait approprié.
Non seulement il n'y a pas de valeur ici ... il y a une valeur négative. La maintenance des commentaires est déjà esquisse dans la plupart des endroits, cela ajoute simplement une autre chose pour que les gens visent. Ces commentaires n'ont aucune valeur pour le lecteur et sont donc obstrués par leur cerveau avec des informations de version inutiles lorsqu'elles pourraient avoir une autre ligne de code dans leur mémoire. C'est aussi une autre ligne d'avoir un conflit de fusion sur (totalement ne pas plaisanter ici..J'ai vu des conflits de conflits sur des commentaires).
Je les trouve utiles, cela permet d'éviter la poursuite par la VCS pour savoir pourquoi une modification a été apportée au code, ou de trouver la bugide pour un défaut, je me souviens que le changement de code était.
Bien que dans la théorie Le VCS contient les informations, en pratique, il peut être enterré, en particulier par des intégrations.
dans d'autres travaux qui sont plus faciles: ou Fondamentalement, le commentaire est une coupe courte autour des VCS et une intégration floconneuse VCS / BugTracking. Je trouve que les commentaires sont également utiles comme marqueur pour: "Cette décision a a été examiné par les clients / comité d'utilisateurs / commission d'examen, et c'est la réponse sélectionnée, faites attention à la modification du comportement ".
Oui, il est vrai qu'il est plus rapide de trouver un numéro de bogue à partir d'un commentaire, mais je dois toujours charger le système de suivi des bogues pour savoir pourquoi. Si cela vaut la peine de commenter, je dirais que cela vaut la peine d'expliquer dans le commentaire pourquoi la valeur par défaut devrait être vraie.
J'ai généralement le traqueur d'insectes ouverts de toute façon - YMMV. Et vous avez raison - vous devez également mettre la raison de la valeur par défaut dans le code. Mon exemple n'est pas le plus grand.
Nous utilisons TFS pour le contrôle de la source. Chaque changement est lié à une tâche ou à un défaut, via la vérification. Dans Visual Studio, cela est intégré, vous pouvez donc visualiser l'historique (annotation) sans beaucoup d'effort.
Vous n'êtes pas à mon humble avis pointilleux. Il y a au moins trois bonnes raisons de ne pas ajouter ce type de commentaires dans le code source:
La ligne ne sait pas bien, quelle serait la différence entre p>
// xyz feature: ... ... // some code
Si voir un commentaire Superfluos fait monter votre tension artérielle, vous devez prendre une consommation d'alcool ou quelque chose.
Cela dit, je conviens que de tels commentaires sont principalement inutiles. Si utilisé de manière cohérente, le programme deviendrait rapidement un labyrinthe de tels commentaires. Que se passe-t-il si une ligne est modifiée une fois pour la version 2.5, puis un an plus tard a changé à nouveau pour Bug 3294? Placez-vous deux commentaires «version» sur la même ligne ou gardez simplement le dernier? Si vous ne conservez que le dernier, vous avez perdu le fait que cela a été ajouté à l'origine pour 2.5. Si vous les gardez les deux, que se passe-t-il quand il y a un troisième changement ou un quatrième? Comment savons-nous ce que l'État était à chaque changement? Que se passe-t-il lorsque vous ajoutez un bloc de code dans la version 2.5, puis pour la version 2.6, vous ajoutez un autre bloc de code incorporé dans le bloc de 2,5? Etc, etc. Le programme pourrait facilement finir par avoir plus de commentaires de version que les lignes de code.
Si non fait de manière cohérente, les commentaires deviendraient rapidement trompeurs. Quelqu'un pourrait mettre un commentaire indiquant que ce bloc a été ajouté pour 2.5, quelqu'un d'autre pourrait insérer du code à l'intérieur de ce bloc pour la version 2.6 et ne pas le commenter, et nous avons maintenant un commentaire qui semble dire que le deuxième bloc a été ajouté à 2,5.
Et faisons-nous cela beaucoup? C'est assez rare que je me soucie quand un changement a été fait. Oh, ok il y a quelques semaines, je me souciais parce que je voulais savoir qui blâmer pour une grande baise.
Comme d'autres ont souligné, les systèmes de contrôle de la version le font pour vous dans les rares occasions lorsque vous en avez besoin. Je suppose que si vous n'aviez aucune sorte de VC, un cas pourrait être fait pour faire cela. Mais vous pouvez obtenir de très bons VCSS gratuitement. Si vous en avez besoin d'un, obtenez-en un. Sinon, vous êtes comme les personnes qui disent que vous devriez vous entraîner à faire de l'arithmétique dans votre tête, car sinon, que feriez-vous si votre calculatrice a cessé de travailler. L'hypothèse étant apparemment qu'à tout moment, toutes les calculatrices du monde pourraient simuler simultanément.
Vous pourriez dire que cela peut aider à pouvoir dire: "Ohhhh, ceci a été ajouté à la commande d'ordre pour soutenir la nouvelle fonction de stockage du vendeur" ou une autre. Mais alors, l'important que ce n'est pas "Ce code a été modifié par BOB pour la version 3.2.4", mais "ce code produit ces données qui ne sont pas utilisées ici mais sont nécessaires par un autre module là-bas".
Je suis un croyant ferme dans la rédaction de commentaires qui introduisent des sections de code et décrivent l'idée générale du code complexe ou autre non évident. Mais c'est une chose entièrement différente.
Je partage votre aversion de cette pratique. Je pense que cela démontre un malentendu des capacités des outils de contrôle de version. J'ai toujours essayé d'éduquer doucement les délinquants. J'ai un problème similaire avec les personnes qui vérifient le code qui contient du code commenté.
Mon problème est que les deux pratiques (commentaires du numéro de défaute et commentant le code pour une utilisation ultérieure) sont tellement plus faciles à utiliser que les alternatives. Je pense que Commenter le code est le problème bien pire, car il laisse beaucoup de détritus totalement morts autour. J'aime les commentaires liés au défaut, car ils fournissent une coupe rapide rapide pour trouver plus de discussions sur le changement.
Ils fournissent également un indice que cette section du code a été réfléchie par un groupe de personnes plus vaste de personnes et que c'est le résultat final, de manière plus prudente de faire des changements fonctionnels.
@Douglas: N'est-ce pas l'endroit où le suivi du problème est entré?
@Tom Cochez: avec vous 100% à ce sujet. Le code commenté Les choses me poussent aussi folle aussi, comme l'une de mes équipes pouvait vous dire ...