Utilisez-vous des commentaires spéciaux sur les corrections de bugs dans votre code?

Question

Certains de mes collègues utilisent des commentaires spéciaux sur leurs correctifs, par exemple:

// 2008-09-23 John Doe - bug 12345
// <short description>

Est-ce que cela a du sens?
Commentez-vous les corrections de bogues d’une manière particulière?

Faites-le moi savoir.

Answer 1

Je ne mets pas de tels commentaires, le système de contrôle de la source conserve déjà cet historique et je suis déjà capable de consigner l'historique d'un fichier.

Je mets bien dans des commentaires qui décrivent pourquoi quelque chose de non évident est en train de se faire. Donc, si la correction de bogue rend le code moins prévisible et plus clair, alors j’explique pourquoi.

Answer 2

Au fil du temps, ceux-ci peuvent s'accumuler et ajouter de l'encombrement. Il est préférable de clarifier le code, d'ajouter des commentaires qui ne sont pas forcément évidents et de conserver les détails du bogue dans le système de suivi et le référentiel.

Answer 3

J'ai tendance à ne pas commenter dans la source réelle, car il peut être difficile de rester à jour. Cependant, je mets des commentaires de liaison dans mon journal de contrôle de source et mon suivi des problèmes. par exemple. Je pourrais faire quelque chose comme ça dans Perforce:

  

[Bug-Id] Problème avec la boîte de dialogue xyz.   Déplacement du code de dimensionnement vers abc et maintenant   initialiser plus tard.

Ensuite, dans mon outil de suivi des problèmes, je vais faire quelque chose comme:

  

Corrigé dans la liste des modifications 1234.

     

Déplacement du code de dimensionnement vers abc and now   initialiser plus tard.

Parce qu’il reste alors un bon marqueur historique. En outre, il est facile, si vous voulez savoir pourquoi une ligne de code particulière est une certaine manière, vous pouvez simplement consulter l'historique des fichiers. Une fois que vous avez trouvé la ligne de code, vous pouvez lire mon commentaire de validation et voir clairement le bogue pour lequel il était et comment je l'ai corrigé.

Answer 4

Seulement si la solution était particulièrement intelligente ou difficile à comprendre.

Answer 5

J'ajoute généralement mon nom, mon adresse e-mail et la date, ainsi qu'une brève description de ce que j'ai changé. En effet, en tant que consultant, je répare souvent le code des autres.

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

Ainsi, les propriétaires de code, ou les personnes qui viendront après moi, pourront comprendre ce qui s’est passé et peuvent entrer en contact avec moi s’ils doivent le faire.

(oui, malheureusement, plus souvent qu'autrement, ils n'ont pas de contrôle de source ... pour les éléments internes, j'utilise le suivi TFS)

Answer 6

Même si cela peut sembler une bonne idée à l’époque, cela devient vite incontrôlable. Ces informations peuvent être mieux capturées grâce à une bonne combinaison de système de contrôle de source et de suivi des bogues. Bien sûr, si quelque chose de délicat se passe, un commentaire décrivant la situation serait utile dans tous les cas, mais pas la date, le nom ou le numéro du bogue.

La base de code sur laquelle je travaille actuellement au travail a environ 20 ans et ils semblent avoir ajouté de nombreux commentaires comme ceux-ci il y a quelques années. Heureusement, ils ont cessé de le faire quelques années après avoir tout transformé en CVS à la fin des années 90. Cependant, de tels commentaires sont toujours présents dans le code et la stratégie consiste maintenant à les "supprimer si vous travaillez directement sur ce code, mais laissez-les sinon". Ils sont souvent très difficiles à suivre, surtout si le même code est ajouté et supprimé plusieurs fois (oui, cela arrive). Ils ne contiennent pas non plus la date, mais contiennent le numéro du bogue que vous devez rechercher dans un système archaïque pour trouver la date, donc personne ne la trouve.

Answer 7

Les commentaires comme celui-ci expliquent pourquoi Subversion vous permet de taper une entrée de journal à chaque validation. C’est là que vous devriez mettre ce genre de choses, pas dans le code.

Answer 8

Je le fais si le correctif concerne quelque chose qui n’est pas simple, mais le plus souvent si le correctif nécessite une longue explication, je le prends comme un signe que le correctif n’a pas été conçu correctement. De temps en temps, je dois travailler autour d'une interface publique qui ne peut pas changer, ce qui tend à être la source de ce type de commentaires, par exemple:

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

Dans d'autres cas, le message de validation du contrôle de code source est ce que j'utilise pour annoter le changement.

Answer 9

Bien que j'ai tendance à voir certains commentaires sur les bogues dans le code au travail, ma préférence personnelle est de lier un code à un bogue. Quand je dis un, je veux vraiment dire un bug. Ensuite, vous pouvez toujours consulter les modifications apportées et savoir à quel bug elles ont été appliquées.

Answer 10

Ce style de commentaire est extrêmement utile dans un environnement multi-développeurs où les développeurs disposent d’un éventail de compétences et / ou de connaissances commerciales (par exemple, partout).

Pour le développeur expérimenté et bien informé, la raison d'un changement peut être évidente, mais pour les développeurs plus récents, ce commentaire les incite à réfléchir à deux fois et à faire plus d'investigations avant de jouer avec. Cela les aide également à en savoir plus sur le fonctionnement du système.

Oh, et une note d'expérience à propos de "Je viens de l'insérer dans le système de contrôle de code source" " commentaires:

Si ce n'est pas dans la source, cela ne s'est pas produit.

Je ne peux pas compter le nombre de fois où l'historique de la source de projets a été perdu à cause de l'inexpérience avec le logiciel de contrôle de la source, des modèles de branchement incorrects, etc. L’historique des modifications ne peut être perdu qu’un seul emplacement - et cela se trouve dans le fichier source.

D'habitude, je le mets d'abord ici, puis je coupe et ne colle pas le même commentaire quand je l'enregistre.

Answer 11

Non, je ne le fais pas et je déteste avoir des graffitis comme ceux-là qui jonchent le code. Les numéros de bogues peuvent être suivis dans le message de validation vers le système de contrôle de version et par des scripts pour envoyer les messages de validation pertinents dans le système de suivi des bogues. Je ne crois pas qu'ils appartiennent au code source, où les modifications futures ne feraient que compliquer les choses.

Answer 12

Souvent, un commentaire comme celui-ci est plus déroutant, car vous n'avez pas vraiment de contexte quant à l'apparence du code d'origine ou du mauvais comportement d'origine.

En général, si votre correctif de bogues fait maintenant fonctionner le code correctement, laissez-le simplement sans commentaires. Il n'est pas nécessaire de commenter le code correct.

Parfois, le correctif rend les choses étranges, ou le test corrige des tests hors du commun. Ensuite, il pourrait être approprié d’avoir un commentaire - en général, le commentaire devrait renvoyer au "numéro de bogue". à partir de votre base de données de bogues. Par exemple, vous pourriez avoir un commentaire disant "Bug 123 - Compte pour un comportement étrange lorsque l'utilisateur est en résolution d'écran 640 sur 480".

Answer 13

Si vous ajoutez de tels commentaires après plusieurs années de maintenance du code, vous aurez tellement de commentaires sur les corrections de bugs que vous ne pourrez plus le lire.

Mais si vous changez quelque chose qui a l'air correct (mais que vous avez un bogue subtil) en quelque chose de plus compliqué, ajoutez un court commentaire expliquant ce que vous avez fait pour que le prochain programmeur qui conserve ce code ne le modifie pas. en arrière parce qu’il (ou elle) pense que vous avez trop compliqué les choses sans raison valable.

Answer 14

Non. J'utilise subversion et saisis toujours une description de ma motivation pour engager un changement. En général, je ne reformule pas la solution en anglais, je résume plutôt les modifications apportées.

J'ai travaillé sur un certain nombre de projets dans lesquels des commentaires ont été insérés dans le code lorsque des correctifs ont été apportés. Fait intéressant, et probablement pas par coïncidence, il s’agissait de projets qui n’utilisaient aucun outil de contrôle de source ou qui étaient tenus de respecter ce type de convention de la part de la direction.

Honnêtement, je ne vois pas vraiment l'intérêt de le faire dans la plupart des situations. Si je veux savoir ce qui a changé, je regarderai le journal de sous-version et le diff.

Seulement mes deux sous.

Answer 15

Si le code est corrigé, le commentaire est inutile et n’intéresse jamais personne - juste du bruit.

Si le bug n'est pas résolu, le commentaire est faux. Alors c'est logique. :) Alors, laissez ces commentaires si vous n'avez pas vraiment résolu le bogue.

Answer 16

Pour localiser un commentaire spécifique, nous utilisons DKBUGBUG - ce qui signifie que le correctif et le relecteur de David Kelley peuvent facilement être identifiés. Nous ajouterons bien sûr Date, ainsi que le numéro de suivi des bogues VSTS, etc.

Answer 17

Ne dupliquez pas les métadonnées que votre VCS conservera pour vous. Les dates et les noms doivent être automatiquement ajoutés par le VCS. Les numéros de ticket, les noms de gestionnaire / utilisateur qui ont demandé la modification, etc. doivent être en commentaires VCS, pas le code.

Plutôt que cela:

// $ DATE $ NAME $ BILLET // commentaire utile à la prochaine pauvre âme

Je voudrais faire ceci:

// commentaire utile à la prochaine pauvre âme

Answer 18

Si le code est sur une plateforme en direct, sans accès direct au référentiel de contrôle de code source, j'ajouterai des commentaires pour mettre en évidence les modifications apportées dans le cadre de la correction d'un bogue sur le système en direct.

Sinon, le message que vous avez entré à l'enregistrement ne devrait pas contenir toutes les informations dont vous avez besoin.

acclamations,

Rob

Answer 19

Lorsque je crée des corrections de bugs / améliorations dans des bibliothèques / composants tiers, je fais souvent des commentaires. Cela facilite la recherche et le déplacement des modifications si je dois utiliser une version plus récente de la bibliothèque / du composant.

Dans mon propre code, je commente rarement les corrections de bugs.

Answer 20

Je ne travaille pas sur des projets à plusieurs personnes, mais j'ajoute parfois des commentaires sur un certain bogue à un test unitaire.

N'oubliez pas qu'il n'y a pas de bugs, mais des tests insuffisants.

Answer 21

Puisque je fais le plus de TDD possible (tout le reste est du suicide social, car chaque autre méthode vous obligera à travailler des heures sans fin), je corrige rarement des bugs.

La plupart du temps, j'ajoute des remarques spéciales comme celle-ci au code:

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

Cela a l'air dur, mais la plupart des gens qui s'appellent eux-mêmes des "développeurs" ne mérite aucune autre remarque.