Est-il bon de conserver les commentaires de correction de bogues dans le code?

Mon équipe utilise clear-case comme contrôle de version. Le projet sur lequel je travaille n'a pas démarré il y a 7-8 ans. Pendant toute la durée de vie du projet, nous avons eu plusieurs versions de service packs de corrections de bogues, etc. Les problèmes sont suivis à l'aide du système de suivi des bogues et la plupart des personnes qui travaillent sur les corrections de bogues suivent une routine consistant à inclure le commentaire dans START / FIN du bloc avec la date, l'auteur, l'ID de bug, etc.

Je pense que cela est tout à fait hors de propos et rend le code encombré et difficile à maintenir et ce sont des choses qui doivent faire partie des commentaires / étiquettes d'enregistrement, etc., où nous pouvons conserver des informations supplémentaires sur le cycle de vie du produit de travail.

Quelle est la meilleure pratique à suivre?

Certains des réviseurs du code insistent pour supprimer les commentaires sur le bogue et les correctifs pour faciliter leur vie. À ma connaissance, ils doivent examiner les fichiers en les mappant à une vue et obtenir le journal des modifications de la branche et l'examiner. Il serait utile que je puisse obtenir quelques bonnes pratiques sur la soumission du code mis à jour pour examen.

Le problème avec l'ajout du correctif en tant que commentaire au code est que vous n'obtenez pas l'histoire complète. Si je vois un morceau de code parfaitement bien étiqueté « ceci est un correctif pour le bug bla », ma première réaction serait de dire « Et alors? ». Le code est là, ça marche. La seule chose que je dois savoir pour maintenir le code est un commentaire qui me dit ce qu'il fait.

Une meilleure pratique serait d'ajouter des références de correction de bogues dans les journaux de validation SCM. De cette façon, vous voyez ce qu'est le bogue, où il a été introduit et comment il a été corrigé. En outre, lorsque vient le temps d'une version, vous pouvez simplement extraire les journaux SCM et ajouter une puce indiquant qu'il y avait un bogue et qu'il a été corrigé. Si une autre branche ou version introduit le même bogue, il est facile de localiser le correctif et de réappliquer s'il s'agit bien de la même chose.

Cela dit, je suis également d'accord avec la réponse de Charles. Si la raison d'un morceau de code n'est pas évidente, par tous les moyens, dites au responsable que le code est là pour une raison et doit être traité avec soin.

Plutôt mauvaise pratique. Je ne dirai pas que cela ne devrait jamais être fait. Parfois, vous rencontrez quelque chose comme un bogue dans une API externe que vous devez contourner. La solution de contournement peut sembler complètement morte si vous ne connaissez pas le bug sous-jacent. Dans ce cas, ce peut être une bonne idée de documenter le bogue dans le code afin que vos collègues ou votre futur individu n'essaient pas de "corriger" le code qui est manifestement mort.

Mauvaise pratique. Les commentaires seront obsolètes et encombreront le code. Les informations sont toujours disponibles dans l'historique des versions de votre système SCC si nécessaire.

Cela ressemble à une mauvaise pratique. Et si votre organisation décide de migrer vers un autre système de suivi des bogues? N'attachez pas trop votre produit aux outils que vous utilisez actuellement. Au lieu de faire référence à des ID de bogue spécifiques, et les raisons pour lesquelles le code semble ne pas être clair, motivez votre décision de conception avec des commentaires dans le code.

Ma première réaction serait de ne pas vous répéter, alors sortez-le du code et dans les journaux SCM. Nous avons eu une discussion similaire ici sur le commentaire de révision pour les fonctions, les noms d'auteurs et les dates de création pour les fichiers et les fonctions. Dans le passé (avant l'utilisation de SCM) toutes ces informations étaient conservées dans les fichiers pour pouvoir reconstituer l'évolution d'un fichier.

Environ la moitié des développeurs souhaitent que ces informations puissent avoir toutes les informations en un seul endroit (cela les incite à rechercher des modifications dans le SCM). L'autre moitié des développeurs ne démarre pas leur recherche d'indices de ce qui a changé dans le coe, mais à partir du SCM afin qu'ils n'aient pas besoin des informations dans le code. Nous n'avons pas encore décidé quoi faire de ces commentaires. Cela dépend beaucoup de la façon dont les gens travaillent et certaines personnes sont très obstinées à abandonner leurs méthodes connues. Même chose pour commenter un bloc de code et les laisser dans le code pour toujours.

Pour ajouter à ce que Dyaster et al. ont dit, bien que JIRA ait de très bonnes capacités pour afficher les changements associés aux corrections de bogues, le meilleur endroit absolu pour documenter une correction de bogue est dans un cas de test. Si le code n'est pas clair sans un commentaire indiquant quel bug a été corrigé, c'est "l'odeur du code". Cela dit, si vous n'avez pas le temps de nettoyer l'odeur, le commentaire devrait faire référence au cas de test, où il devrait être beaucoup plus évident pourquoi le code fait ce qu'il fait. Si vous n'avez pas le temps d'écrire un cas de test expliquant la correction du bogue, alors le bogue n'a pas encore vraiment été corrigé, il a juste été reporté.

Je serais d'accord avec l'ajout d'ID de correction de bogues dans les messages de validation, et non dans le code lui-même. Les suiveurs de bogues qui récupèrent automatiquement les messages de validation pour les ID de bogue sont très utiles.

De plus, vous pouvez utiliser la commande blame / annotate / louange de votre système de contrôle de version pour remplacer ces commentaires. Ensuite, lorsque vous exécutez quelque chose comme:

vcs blame file.ext

vous pouvez voir des informations utiles, y compris généralement qui a changé chaque ligne, quand ils l'ont changé et l'ID de validation. À partir de l'ID de validation, vous pouvez obtenir le message complet, qui doit inclure l'ID de bogue.

De bons systèmes VCS vous permettront d'ignorer les espaces lors du calcul de qui a modifié une ligne.

Je ne sais pas ce que Clear Case a pour cette fonctionnalité.