Commentaires de maintenance

Question

Quelles techniques spéciales utilisez-vous pour modifier le code existant?

Exemple: supposons que vous modifiiez une règle de gestion dans une méthode. Marquez-vous la section modifiée avec des commentaires spéciaux?

Toutes les normes de codage / commentaires que vous utilisez lors de la modification du code?

Answer 1

Vous voulez dire quelque chose comme:

foo();  // changed by SecretWiz, 20090131

Je ne recommanderais pas cela. Il encombre les fichiers de code et le système de contrôle de version devrait le gérer pour vous. Il garde la trace de qui a changé quoi. Utilisez

svn blame

Answer 2

Si je fais quelque chose comme réparer un bogue relativement obscur, en gros tout ce qui ne dit pas pourquoi j'ai écrit le code comme je l'ai fait, je vais généralement ajouter un commentaire pour l'expliquer, de sorte que moi (ou quelqu'un d'autre) sinon, si quelqu'un d'autre modifiait mon code ;-) ne le supprimerais pas accidentellement plus tard.

Answer 3

Une chose que j’essaie toujours de faire est d’insérer l’ID de bogue (ou l’ID de demande de fonctionnalité) dans le système de suivi des bogues dans les commentaires d’archivage de code que j’ai effectués pour ce changement. J'ajoute quelque chose comme & "Voir les commentaires pour ce bogue / cette fonctionnalité dans bugzilla pour plus de détails &"; Là, je peux et généralement expliquer la raison de ce changement de code. Cela signifie que toutes les modifications ou au moins toutes les modifications importantes doivent être suivies via une demande de fonctionnalité / un ID de bogue. J'ai souvent créé un bogue juste pour expliquer en détail les raisons commerciales impliquées.

Answer 4

Non, c'est une très mauvaise idée. Votre contrôle de source conserve un historique de toutes les modifications. Si vous voulez autre chose, faites une entrée dans votre outil de suivi des bogues. Il n'est pas nécessaire de commenter les anciennes sections de code ou de le jeter avec des choses comme:

// modified by A.B. on 11/23/99 to fix issue #123456

J'ai vu des commentaires comme celui-ci dans notre base de code et ils n'ont aucun sens pendant des années. Qui diable est A.B., et quel était le problème # 123456? Si le code existe toujours, cela signifie-t-il que quelqu'un envisage de reprendre ces modifications dans le futur?

Ces commentaires n'ont aucune valeur et servent uniquement à encombrer votre code.

Answer 5

Je suggérerais de créer une méthode & amp; appelez cela depuis le code en cours de modification.
Nommez également la méthode pour en suggérer le but / l’intention.

par exemple. GiveRebateIfValidCoupon();

Answer 6

& "Toute norme de codage / commentaire que vous utilisez pour modifier le code? &";

Oui. Faire de nouvelles sous-classes. Laissez l'ancien code seul, sauf dans les rares cas où vous ne l'avez pas testé correctement et que vous aviez réellement tort.

Les modifications apportées aux exigences impliquent l’ajout de sous-classes et de nouveaux tests pour gérer les nouvelles règles commerciales.

Answer 7

La seule fois où j'ajoute des commentaires spéciaux, c'est si la modification est censée être temporaire. Dans cette situation, je le marque avec un mot clé standard (par exemple, TEMPFIX) afin de pouvoir le retrouver plus tard. Bien sûr, vous devez ensuite vous rappeler de supprimer le code ou d’apporter une modification permanente, mais pour certains projets, nous l’imposons à l’aide d’une macro nous permettant de spécifier une date d’expiration après laquelle le code cesse de se compiler.

En dehors de cela, nous nous appuyons sur le contrôle de source.

Answer 8

Le code doit être conforme à vos normes de codage et à celles de votre organisation.

Donc, non, il ne devrait pas y avoir de commentaire particulier indiquant que le code a été modifié - en tout ou du moins, le code sera modifié tôt ou tard.

S'il existe un code dont vous avez hérité et qui ne correspond pas aux normes de commentaire, alors rajoutez des commentaires, car refactoriser le code. Si le code est vraiment ancien et non documenté, cela signifie naturellement l'ajout de documentation.

Il est bon de comprendre le code avant de le modifier (au passage).

Answer 9

Normalement, je vais simplement changer le code et faire enregistrer mes commentaires dans mon contrôle de code source. Dans l'outil de suivi des tâches de votre choix, vous pouvez référencer la révision où la tâche a été implémentée.

Parfois, je sais que certaines fonctionnalités vont changer, changer de nom, etc. en fonction de la manière dont les besoins des utilisateurs sont débattus. Dans ce cas particulier, je conserverai l'ancienne version et la commenterai. Il devient alors trivial de simplement supprimer le commentaire plus tard, plutôt que de passer par le contrôle de code source à la recherche de l'ancienne version. Cela peut également sauver le cul de quelqu'un s'il doit maintenir votre code ultérieurement, car lorsque les utilisateurs changeront à nouveau d'avis, l'exigence sera déjà inscrite dans le code et ne sera pas commentée.

Answer 10

Je suis d’accord avec beaucoup d’autres personnes ici sur SO. & "Si vous n'avez pas besoin de quelque chose dans votre code, supprimez-le &". Surtout dans le code de production, la dernière chose que vous voulez, c'est beaucoup de fouillis. Il pourrait être beaucoup plus facile pour quelqu'un de comprendre le fonctionnement de votre modification que de lire votre commentaire de maintenance et de vous embrouiller.

Je conservais l'ancien code obsolète dans mes projets, mais au fil du temps, un projet qui n'aurait dû contenir que quelques milliers de lignes finissait par dépasser 10 000 et était difficile à gérer.