Bonne idée de mettre des numéros de bogues dans un commentaire au début du fichier source?
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?
J'ai déjà vu cela fait auparavant, à la fois manuellement par les auteurs et automatiquement par des scripts et des déclencheurs intégrés aux systèmes de contrôle de version pour ajouter des informations sur l'auteur, le commentaire d'enregistrement et la date dans le fichier.
Je pense que les deux méthodes sont assez terribles pour deux raisons principales. Tout d'abord, il ajoute de l'encombrement et du bruit au fichier, d'autant plus que ces commentaires vieillissent et deviennent inutiles à l'état actuel du fichier. Deuxièmement, ce sont des informations en double de ce qui est déjà conservé dans le système de contrôle de version, et si vous utilisez un système de contrôle de version moderne qui prend en charge les ensembles de modifications, cela perd en fait des informations sur les modifications.
Si quelque chose, 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'enregistrement à 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 fournir un lien de cette façon. Bien sûr, cela vient avec l'inconvénient d'une dépendance à l'égard de ces outils pour le projet.
Il y a exactement un cas où je ferais cela, à savoir dans le cadre d'un avertissement pour les futurs programmeurs: "N'appelez pas la fonction foo() ici directement; cela a provoqué le bogue # 1234, à savoir ...", puis une brève description du bogue suit.
Et si le code a changé de manière à ce qu'il n'y ait pas de tentation d'appeler directement foo(), supprimez ce commentaire. Cela ne ferait qu'irriter et faire exploser le code.
C'est une pratique tout à fait horrible. Il ajoute des efforts afin d'obtenir un effet qui est une pure duplication; en d'autres termes, la seule chose qu'il ajoute en utilisant uniquement les journaux de validation est la possibilité de créer une incohérence. Vos fichiers source sont encombrés de quantités illimitées de choses que vous ne regardez jamais.
Le seul avantage que je puisse discerner 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 personnes sont suffisamment compétentes pour suivre les subtilités du développement logiciel, tout en étant simultanément incapables de comprendre le contrôle de version.
C'est, à mon humble avis, une très mauvaise idée. Après la révision numéro 100, vous aurez 90% de commentaires et 10% de code. Je ne considérerais pas cela comme propre et lisible.
Le seul point que je vois est lorsque vous devez échanger votre code entre SCC et, 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 d'historique de cette façon, vous perdrez l'historique des différences aussi, donc enregistrer les commentaires ne vous aidera que légèrement).
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 n'était que des sauvegardes dans des fichiers zip).
Je vois que tout le monde est opposé à l'idée et a donné une raison historique (l'ère du contrôle pré-source) 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 ils marquent également le numéro de bogue autour du morceau de code. Je trouve parfois cela utile lorsque vous voyez un bogue dans le code et vous pouvez trouver instantanément le correctif de bogue qui a introduit ce problème. Si nous n'avons pas 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 morceau de code est là.
L'un des points du test Joel est
Avez-vous une base de données de bogues?
Ces informations peuvent être conservées dans une base de données de bogues si vous pensez qu'elles sont importantes, mais elles ne seraient que du bruit dans les commentaires.
Je pense que vous avez deux problèmes ici. Premièrement, pourquoi devriez-vous vous fier uniquement au diff alors que 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 trouver des lignes de code balisées qui ne sont plus nécessaires. Les commentaires à l'intérieur du 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 acquises rendent la base de code plus facile à travailler 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 creuser dans l'historique et éventuellement consulter les différences. J'ai reçu une demande de "revenir à la formule d'origine". Je savais où aller dans l'historique des révisions et je n'ai passé en revue qu'un ou deux différentiels.
Personnellement, le code remarqué ressemble à un travail en cours pour un problème qui est résolu par essais et erreurs. Sortez ce bordel du code de production. Pouvoir facilement glisser des lignes de code vers l'intérieur et vers l'extérieur ne fait que faciliter la confusion.
Si vous n'avez pas de VCS avec des messages de validation et aucun système de suivi des bogues avec une option pour laisser des commentaires, c'est une option, et non la meilleure, pour suivre les changements.
Mieux vaut avoir une feuille de calcul avec ces informations, ou si vous êtes dans un environnement sans ces "luxes", un fichier texte assis quelque part près de vos sources.
Mais je recommanderais fortement si vous êtes dans un tel environnement de commencer à construire un dossier pour investir dans un VCS et un système de suivi des bugs :)
Non, ce n'est pas une bonne pratique de suivre vos corrections de bogues en tant que commentaires dans le code. Cela ne fait qu'encombrer.
Je dirai également la même chose pour le message de copyright que vous avez mentionné. Si personne en dehors 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 veut fouiller dans les en-têtes de chaque fichier de code pour générer des notes de publication ou voir un aperçu des modifications qui ont été apportées. Ces journaux des modifications doivent tous être stockés ensemble, soit dans votre historique de suivi des versions, votre outil de suivi des défauts, ou les deux.
Si vous cherchez une bonne lecture à ce sujet, je recommande le chapitre quatre de Clean Code .
Gardez cela à l'esprit - le code est souvent plus long que les outils qui le prennent en charge. Autrement dit, les trackers de problèmes, le contrôle de version et tous les autres scripts évolueront au cours du développement. Les informations se perdent.
Bien que je sois d'accord, l'encombrement des fichiers est ennuyeux, l'ouverture d'un fichier et la compréhension de son historique sans recourir aux outils ont toujours été très utiles, surtout si je maintiens le code.
Personnellement, je pense qu'il y a de la place pour les outils et le journal de code.
Je sais Git ne fait pas cela et la réponse simple est "pourquoi diable irait-il là-bas?"
C'est une conception moins modulaire en général. Avec cette solution, les fichiers sont désormais un mélange entre le contenu et les métadonnées. Amazon S est un autre exemple de service de stockage de fichiers qui n'ajoute pas YAML front-matter ou similaire aux fichiers.
Tout consommateur d'un fichier doit d'abord le traiter via le système de contrôle de version. C'est un couplage serré, par ex. votre favori IDE se cassera s'il ne prend pas en charge votre VCS.
Je pense qu'il y a d'autres éléments dans cette discussion qui sont souvent oubliés mais ce sont 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, mettre un court commentaire de révision dans la portée correcte (méthode ou classe) indiquant qu'une modification a été apportée peut être très utile pour résolution rapide des conflits de fusion ou d'archivage.
De même, lorsque vous travaillez dans un environnement où plusieurs branches (fonctionnelles) sont impliquées, il est plus facile pour une troisième personne (maître de build) d'identifier ce qu'il faut faire pour résoudre les conflits potentiels.
Chaque fois que vous devez vous éloigner de la 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 à réduire ou à éliminer la plupart 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é des fonctions lorsque nous devions compter sur des outils externes (par exemple javadocs) pour créer des notes de publication à partir du code. Il est principalement inutile ou redondant avec les outils de contrôle de version modernes.
Cela ne peut avoir de sens que comme commentaire dans un morceau de code très modulaire, si l'on doit recourir à un codage obscur ou non stellaire que les futurs développeurs seraient tentés de changer - sans en connaître la raison - comme dans une solution de contournement à un bug/insuffisance de la bibliothèque.
Je ne mettrais certainement pas de telles informations au début du fichier - généralement une telle chose appartient à un système de ticket.
Il existe cependant des cas où des références au système de tickets et/ou à d'autres documents ont un sens. Par exemple, s'il y a une longue explication de la conception ou une description des alternatives. Ou des informations sur la façon de tester les choses, ou des explications sur la raison pour laquelle cela a été fait de cette façon. Si c'est court, il appartient au fichier lui-même; si elle est longue et/ou concerne 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 encore sur le projet ne s'y ajoute. La plupart d'entre eux pensent que c'est un gaspillage inutile d'espace, car il est de loin inférieur au suivi des erreurs de bug dans un fichier à l'aide de notre système de contrôle de version.
Dans certains fichiers critiques qui ont subi de nombreuses corrections et améliorations, ces listes sont devenues si grandes que vous devez les faire défiler pour accéder au code. Lors de la greping ces listes peuvent entraîner plusieurs faux positifs comme 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 massif et chaotique d'espace qui rend le code plus difficile à parcourir et à localiser.