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

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?

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.

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.

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.

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).

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).

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à.

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.

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.

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 :)

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.

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.

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 .

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.

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.

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.

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.