Bonne idée de mettre les numéros de bugs dans un commentaire au début du fichier source? [fermé]

40

Est-ce une bonne pratique de mettre des numéros de bogues dans le fichier lui-même dans un commentaire d'en-tête?

Les commentaires ressembleraient à ceci:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Cela semble utile, mais est-ce considéré comme une mauvaise pratique?

Geek
la source
23
La question que je poserais est "Que pouvez-vous faire avec les numéros de bogues intégrés que vous ne pouvez pas déjà faire avec votre base de données de bogues?" Je ne peux penser à aucun cas d'utilisation réel.
M. Dudley
6
@JensG C'est pourquoi vous le mettez dans le message commit, et un logsur le fichier vous donnera à peu près exactement la même chose, mais sans encombrer le fichier ...
Izkata
1
@JensG Et quand vous avez corrigé des scores ou des centaines de défauts sur un fichier particulier? La réponse évidente est que vous effacez périodiquement les identifiants obsolètes, mais vous revenez ensuite à la récupération du journal VC ...
dmckee
3
Cette question est le sujet de l'article d'Ars Technica. Faut-il lister les bugs dans l'en-tête d'un fichier source? (publié 15 jours après la publication de cette question).
Peter Mortensen

Réponses:

107

Je l'ai déjà fait auparavant, à la fois manuellement par les auteurs et automatiquement par les scripts et les déclencheurs intégrés aux systèmes de contrôle de version pour ajouter des informations sur l'auteur, le commentaire d'archivage et la date au fichier.

Je pense que les deux méthodes sont assez terribles pour deux raisons principales. Premièrement, cela ajoute du fouillis et du bruit au fichier, d’autant plus que ces commentaires vieillissent et deviennent inutiles pour l’état actuel du fichier. Deuxièmement, il s'agit d'informations dupliquées provenant de ce qui est déjà géré dans le système de contrôle de version. Si vous utilisez un système de contrôle de version moderne prenant en charge les ensembles de modifications, vous perdez en fait les informations relatives aux modifications.

Si possible, envisagez l'intégration avec votre système de suivi des défauts. Certains outils vous permettent de lier un numéro d'identification de défaut ou de tâche dans un commentaire d'archivage à un élément de l'outil de suivi. Si vous avez tous vos défauts, demandes d'amélioration et tâches de travail dans l'outil, vous pouvez établir un lien de cette manière. Bien sûr, cela vient avec les inconvénients d’une dépendance à ces outils pour le projet.

Thomas Owens
la source
2
"et si vous utilisez un système de contrôle de version moderne qui prend en charge les ensembles de modifications, il perd en réalité des informations sur les modifications." - Pouvez-vous élaborer s'il vous plaît?
Geek
10
@ Geek Je ne sais pas quoi expliquer. Si vous regardez un fichier qui fait référence à un numéro d'identification de bogue, vous ne verrez pas d'autres fichiers modifier à la suite de ce même défaut, sauf si vous effectuez une recherche dans les fichiers. C'est ce qu'est un ensemble de modifications: une collection de fichiers archivés ensemble.
Thomas Owens
9
J'ajouterais également que si vous passez à un nouveau système de suivi des bogues, ces chiffres deviennent instantanément inutiles. Je rencontre ce problème dans mon travail actuel où certains commentaires portent des chiffres provenant d'un logiciel de suivi des bogues qui n'ont pas été utilisés depuis 10 ans.
17 du 26
2
Ainsi, après avoir adopté le nouveau système de suivi des bogues, ils deviennent aussi utiles que s’ils n’étaient jamais là. Mais en supposant qu'ils aient fourni une certaine valeur à un moment donné et qu'ils ne fournissent aucune valeur négative maintenant, pourquoi ne pas le faire?
Cruncher
@ 17of26 - J'imagine que vous pouvez relier d'anciens bogues / problèmes à de nouveaux, si ce n'est par un autre mécanisme que comme un commentaire du type "ancien problème de suivi des problèmes 1234".
Kenny Evitt
42

Il y a exactement un cas où je le ferais, à savoir dans le cadre d'un avertissement destiné aux futurs programmeurs: "N'appelez pas la fonction foo()ici directement; cela a provoqué le bogue n ° 1234, à savoir ...", puis une brève description du le bug suit.

Et si le code a changé de manière à ne pas être tenté d'appeler foo()directement, supprimez ce commentaire. Cela ne ferait qu'irriter et faire exploser le code.

rem
la source
19
Peut-être suis-je un peu dur à cuire, mais s'il foo()ne faut pas appeler directement, le code doit être structuré de manière à ne pas pouvoir l'être.
MetaFight
20
Oh, j'ai essayé d'écrire quelque chose à titre d'exemple, pour rendre le texte plus concret - ne me prenez pas trop à la lettre. Un meilleur cas serait un cas où vous utilisiez une bibliothèque externe et où la fonction que vous utiliseriez normalement dans un but spécifique comportait un bogue. Ensuite, un commentaire "Ne pas appeler foo()ici" serait raisonnable.
rem
16

C'est une pratique tout à fait horrible. Cela demande un effort supplémentaire pour obtenir un effet de duplication pure; en d'autres termes, la seule chose qu'il ajoute au-delà de l'utilisation des journaux de validation est la possibilité de créer une incohérence. Vos fichiers source sont encombrés d'une quantité illimitée d'éléments que vous ne regardez jamais.

Le seul avantage que je puisse percevoir est que vous pouvez reconstruire l’historique des sources sans accéder au contrôle de version, par exemple lors de l’étude d’une impression. Mais très peu de gens sont suffisamment compétents pour suivre les subtilités du développement logiciel, tout en étant incapables de comprendre le contrôle de version.

Kilian Foth
la source
À votre avis, combien de bogues sont possibles dans un fichier et s’il y en a beaucoup, c’est probablement le temps d’une réécriture.
Andy
11

Non.

C'est ce que les gens faisaient avant d'utiliser un système de contrôle de version (c'est-à-dire lorsque le code source était simplement une sauvegarde dans un fichier zip).

Neil Barnwell
la source
2
qui était une sorte de système de contrôle de version (et un que j’ai vu utilisé de manière opérationnelle dans des sociétés de logiciels aussi tôt que 2006, et est sans doute utilisé quelque part aujourd’hui).
Jwenting
1
@jwenting J'ai vu sur ce site des questions émanant de personnes qui ont la malchance de travailler actuellement dans des magasins où il en est de pratique courante :-(
Carson63000
Nous utilisons un excellent système de contrôle de source. Personne d'autre que moi ne met des commentaires lors de la vérification du code. <haussement d'épaules> Je commente certaines choses (comme PLSQL qui n'est pas toujours suivi par SCM). Je commente mon code pour l'expliquer, mais ne le rattache jamais à un bogue particulier, mais je fais toujours référence aux bogues dans les commentaires de validation du SCM lors de l'enregistrement. J'espère qu'un jour, quelqu'un l'appréciera.
Pedantic
11

C'est, à mon humble avis, une très mauvaise idée. Après le numéro de révision 100, vous aurez 90% de commentaires et 10% de code. Je ne considérerais pas cela comme propre et lisible.

Le seul point à ce sujet, c’est que vous devez échanger votre code entre les SCC et que, pour une raison quelconque, vous ne pouvez pas transférer l’historique entre les deux systèmes (mais même lorsque vous enregistrez les commentaires de l’historique de cette façon, vous perdrez l’historique des diff. ainsi, enregistrer les commentaires ne vous aidera qu'un peu).

Doc Brown
la source
8

Je vois que tout le monde s’oppose à l’idée et donne une raison historique (à l’époque du contrôle de source avant) de la raison pour laquelle les gens le faisaient.

Cependant, dans ma société actuelle, les développeurs de bases de données suivent cette pratique et marquent en outre le numéro de bogue autour du morceau de code. Je trouve parfois cela utile lorsque vous voyez un bogue dans le code et que vous pouvez trouver instantanément le correctif qui a introduit ce problème. Si nous ne disposons pas de ces informations dans mon package de base de données, il ne sera certainement pas facile de trouver la cause première de cette implémentation.

Oui, cela encombre le code, mais cela aide à trouver la raison pour laquelle ce code est là.

Parvez
la source
3
Absolument. Parfois, j'ai le léger sentiment que les programmeurs sont horrifiés par la redondance, ils évitent ainsi d'avoir la même information accessible de différentes manières. C'est très intéressant, car les programmeurs sont généralement horrifiés par les mauvaises performances et utilisent donc des caches dans leurs programmes. Mais la mise en cache des numéros de bogues dans le code à côté de l'endroit où ils sont le plus utiles est considérée comme mauvaise? Mmmh.
JensG
Il y a souvent un autre moyen d'obtenir cette information (sur le projet sur lequel je travaille, ce serait de faire right click > Team > Show Annotationsporter le blâme sur le fichier en cours), mais la différence est que, avec les commentaires, il y a une possibilité de découverte - ils peuvent vous attaquer - et avec les annotations, vous devez décider consciemment d'aller les chercher.
David Conrad
Pensez, décidez, cliquez, cliquez, cliquez, faites défiler. C'est pourquoi j'ai dit "mettre en cache dans le code". Si c'est là, je viens de le voir.
JensG
2
@JensG Point de vue intéressant. Les caches peuvent améliorer les performances mais ont également un coût de portage. Si la cache doit être remplie, mise à jour, invalidée, vidée, etc., par un effort humain redondant, je m'interroge sur le rapport coûts / avantages, en particulier compte tenu de la gravité des efforts déployés par les humains pour maintenir de telles constructions dénormalisées synchronisées.
Jeffrey Hantin
7

L’un des points de l’ essai de Joël est

Avez-vous une base de données de bugs?

Ces informations peuvent être conservées dans une base de données de bogues si vous pensez qu'elles sont importantes, mais elles ne constitueraient qu'un bruit dans les commentaires.

Pierre Arlaud
la source
1
Voir l'exemple dans la question - les commentaires feraient référence à la base de données de bogues ...
Izkata
@ Izkata Mais c'est le point. La base de données elle-même peut avoir un champ "commentaire" avec le commentaire. La question n'est pas de savoir si une base de données de bogues a été créée ou non, mais plutôt de savoir si le conserver dans le fichier source est une bonne idée. Je pense que même s’il s’agit de commentaires, ils devraient être conservés dans la base de données car c’est à cela que sert.
Pierre Arlaud
6

Je pense que vous avez deux problèmes ici. Premièrement, pourquoi devriez-vous vous fier uniquement au diff lorsque la plupart des systèmes vous permettent de saisir des commentaires de révision? Comme de bons commentaires de code, vous découvrez pourquoi le changement a été effectué et pas seulement le changement lui-même.

Deuxièmement, si vous avez cette capacité, faites-en une bonne pratique de les mettre tous au même endroit. Il n'est pas nécessaire de parcourir le fichier pour rechercher des lignes de code délimitées qui ne sont plus nécessaires. Les commentaires dans le code de travail sont là pour vous expliquer pourquoi il est codé de cette façon.

Une fois que vous avez mis cela en pratique, les habitudes développées facilitent le travail de la base de code pour tout le monde.

Le suivi des bogues et des fonctionnalités associés, ainsi que les raisons pour lesquelles vous modifiez ce fichier, peuvent vous donner une idée de la profondeur à laquelle vous devez plonger dans l'historique et, éventuellement, examiner les différences. J'ai eu une demande pour "revenir à la formule d'origine." Je savais exactement où aller dans l'historique des révisions et n'ai passé en revue qu'un ou deux diffs.

Personnellement, le code remarqué ressemble à un travail en cours pour un problème qui est résolu par essais et erreurs. Obtenez ce désordre de code de production. Etre capable de glisser facilement des lignes de code dedans et dehors ne fait que faciliter la confusion.

JeffO
la source
2

Si vous n'avez pas de VCS avec des messages de validation et pas de système de suivi des bogues avec une option permettant de laisser des commentaires, c'est une option, et non la meilleure, pour suivre les modifications.
Mieux vaut avoir une feuille de calcul contenant ces informations ou, si vous êtes dans un environnement sans luxe, un fichier texte situé quelque part près de vos sources.
Mais si vous êtes dans un tel environnement, je vous recommande fortement de commencer à construire une affaire en faveur de l'investissement dans un système de VCS et de suivi des bogues :)

jwenting
la source
2

N'oubliez pas ceci: le code dure souvent plus longtemps que les outils qui le prennent en charge. Autrement dit, les outils de suivi des problèmes, le contrôle de version et tous les autres scripts évolueront au cours du développement. L'information se perd.

Bien que je sois d’accord, le fouillis de fichiers est ennuyeux; ouvrir un fichier et en comprendre l’historique sans avoir recours à des outils a toujours été très utile, en particulier si je tiens à jour le code.

Personnellement, je pense qu'il y a de la place pour les outils et le journal en code.

ggb
la source
2

Je sais que Git ne le fait pas et la réponse est simple : « pourquoi diable serait il y aller? »

C'est une conception moins modulaire en général. Avec cette solution, les fichiers sont maintenant un mélange de contenu et de métadonnées. Amazon S3 est un autre exemple de service de stockage de fichiers qui n'ajoute pas de matière première YAML ou similaire aux fichiers.

Tout consommateur de fichier est obligé de le traiter d'abord via le système de contrôle de version. Il s’agit d’un couplage étroit. Par exemple, votre IDE préféré se cassera s’il ne prend pas en charge votre VCS.

djechlin
la source
2

Non, il n'est pas recommandé de suivre vos corrections de bogues sous forme de commentaires dans le code. Cela ne génère que du fouillis.

Je dirai également la même chose pour le message de copyright que vous avez mentionné. Si personne de l'extérieur de votre entreprise ne verra jamais ce code, il n'y a aucune raison d'inclure un message de copyright.

Si vous utilisez un logiciel de suivi de version ( Git , SVN , etc.), vous devez inclure ces notes dans vos messages de validation. Personne ne souhaite fouiller dans les en-têtes de chaque fichier de code pour générer des notes de publication ou avoir un aperçu des modifications apportées. Ces journaux de modifications doivent tous être stockés ensemble, soit dans votre historique de suivi des versions, votre système de suivi des incidents ou les deux.

Si vous recherchez une bonne lecture à ce sujet, je vous recommande le chapitre quatre de Clean Code .

Brian
la source
Les avis de droits d'auteur sont également là pour informer (légèrement légèrement redondant) les employés que le fichier appartient à l'employeur. Et peut - être dissuade le partage illégal (même par les employés), à en juger par le nombre de personnes semblent penser que le droit d' auteur applique seulement s'il est un avis.
Bernd Jendrissek
1

Je pense qu'il y a d'autres éléments dans cette discussion qui sont souvent oubliés, mais il y a des cas où certains commentaires de révision sont rapides pour une équipe.

Lorsque vous travaillez dans un environnement d’équipe avec une base de code partagée et où plusieurs membres de l’équipe travaillent potentiellement dans les mêmes zones de code, il peut être très utile de placer un court commentaire de révision dans la portée correcte (méthode ou classe) indiquant que la modification a été effectuée. résoudre rapidement les conflits de fusion ou d’archivage.

De même, lorsque vous travaillez dans un environnement où plusieurs branches (fonctionnalités) sont impliquées, il est plus facile pour une troisième personne (maître de la construction) d'identifier ce qu'il faut faire pour résoudre les conflits potentiels.

Chaque fois que vous devez quitter l'IDE et demander à quelqu'un pourquoi ils ont changé quelque chose, cela perturbe la productivité des deux membres de l'équipe. Une note rapide dans la bonne portée peut aider à atténuer ou à éliminer la majeure partie de cette interruption.

StingyJack
la source
3
la question concerne le commentaire au début du fichier source, juste après le message de copyright - cela n'a rien à voir avec les commentaires dans les portées plus étroites
gnat
Toutes les réponses ici parlent de cela, cependant. Si j'apporte des modifications importantes à l'ensemble du fichier de classe (correction de la réorganisation ou de la mise en forme), ne commenterais-je pas le fichier de classe comme étant l'étendue?
StingyJack
0

Toute information de bogue directement associée à un morceau de code devient non pertinente lorsque l'intégrité de l'ensemble du changement est modifiée par un correctif successif.

Auparavant, il était courant d’ajouter des informations dans le résumé de la fonction lorsque nous devions nous servir d’outils externes (javadocs, par exemple) pour créer des notes de publication à partir du code. Il est généralement inutile ou redondant avec les outils de contrôle de version modernes.

Ce commentaire n’a de sens que dans un code très modulaire, s’il faut recourir à un codage obscur ou non stellaire que les futurs développeurs seraient tentés de modifier - sans en connaître la raison - comme dans une solution de contournement. bug de bibliothèque / défaut.

Fiammetta Castaldi
la source
0

Je ne mettrais certainement pas de telles informations au début du fichier - une telle chose appartient généralement à un système de tickets.

Il existe toutefois des cas où les références au système de tickets et / ou à d'autres documents ont du sens. Par exemple, s’il existe une longue explication de la conception ou une description des solutions de remplacement. Ou des informations sur la façon de tester des choses, ou des explications pour expliquer pourquoi cela a été fait exactement de cette façon. Si c'est court, il appartient au fichier lui-même; si c'est long et / ou s'il s'agit d'une image plus grande, vous voudrez probablement la mettre ailleurs et la référencer.

moins
la source
cela ne semble pas ajouter une valeur substantielle à ce qui a déjà été posté dans les réponses précédentes
gnat
0

Le projet auquel je suis actuellement affecté au travail avait ce type de liste de numéros de bogues au début de chaque fichier; cependant, aucun des développeurs toujours sur le projet ne l'ajoute plus. La plupart d'entre eux pensent que c'est un gaspillage d'espace inutile, car il est de loin inférieur au suivi des erreurs commises dans un fichier à l'aide de notre système de contrôle de version.

Dans certains fichiers critiques ayant subi de nombreuses corrections et améliorations, ces listes sont devenues si grandes que vous devez les faire défiler pour obtenir le code. Lors de la création de ces listes, plusieurs faux positifs peuvent apparaître car un titre de bogue court ou une courte description est répertorié avec chacun.

En bref, ces listes sont au mieux inutiles et au pire un gaspillage d'espace massif et chaotique qui rend le code plus difficile à parcourir et à localiser.

Fred Thomsen
la source