Je considère généralement ces commentaires comme une mauvaise pratique et je pense que ce type d'informations appartient aux journaux de validation SCM. Cela rend le code plus difficile à lire dans la plupart des cas.
Cependant , je fais encore souvent quelque chose comme ça pour des types spécifiques de modifications.
Cas 1 - Tâches
Si vous utilisez un IDE comme Eclipse, Netbeans, Visual Studio (ou si vous avez un moyen de faire des recherches de texte sur votre base de code avec autre chose), votre équipe utilise peut-être des "balises de commentaire" ou des "balises de tâche" spécifiques. Dans ce cas, cela peut être utile.
Je voudrais de temps en temps, lors de l'examen du code, ajouter quelque chose comme ceci:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
ou:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
J'utilise différentes balises de tâche personnalisées que je peux voir dans Eclipse dans la vue des tâches pour cela, car avoir quelque chose dans les journaux de validation est une bonne chose mais pas suffisant lorsque vous avez un cadre vous demandant lors d'une réunion de révision pourquoi le bugfix XY a été complètement oublié et a glissé à travers. Donc, sur des questions urgentes ou des morceaux de code vraiment douteux, cela sert de rappel supplémentaire (mais généralement je garderai le commentaire court et vérifierai les journaux de validation parce que c'est à ça que sert le rappel, donc je n'encombre pas trop le code beaucoup).
Cas 2 - Correctifs de libs tiers
Si mon produit doit empaqueter un morceau de code tiers en tant que source (ou bibliothèque, mais reconstruit à partir de la source) parce qu'il devait être corrigé pour une raison quelconque, nous documentons le correctif dans un document séparé où nous listons ces "mises en garde" pour référence future, et le code source contiendra généralement un commentaire similaire à:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Cas 3 - Corrections non évidentes
Celui-ci est un peu plus controversé et plus proche de ce que demande votre développeur senior.
Dans le produit sur lequel je travaille en ce moment, nous avons parfois (certainement pas une chose courante) un commentaire comme:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Nous ne le faisons que si le correctif n'est pas évident et que le code se lit anormalement. Cela peut être le cas pour les bizarreries du navigateur par exemple, ou les correctifs CSS obscurs que vous devez implémenter uniquement parce qu'il y a un bogue de document dans un produit. Donc, en général, nous le lions à notre référentiel de problèmes interne, qui contiendra ensuite le raisonnement détaillé derrière le correctif et des pointeurs vers la documentation du bogue du produit externe (par exemple, un avis de sécurité pour un défaut bien connu d'Internet Explorer 6, ou quelque chose comme ca).
Mais comme mentionné, c'est assez rare. Et grâce aux balises de tâche, nous pouvons les parcourir régulièrement et vérifier si ces correctifs étranges ont toujours un sens ou peuvent être supprimés (par exemple, si nous avons abandonné la prise en charge du produit buggy à l'origine du bogue).
Ceci juste dans: Un exemple réel
Dans certains cas, c'est mieux que rien :)
Je suis juste tombé sur une énorme classe de calcul statistique dans ma base de code, où le commentaire d'en-tête était sous la forme d'un journal des modifications avec le yadda yadda habituel: relecteur, date, ID de bogue.
Au début, j'ai pensé à la mise au rebut, mais j'ai remarqué que les ID de bogue ne correspondaient pas seulement à la convention de notre outil de suivi des problèmes actuel, mais ne correspondaient pas non plus à celui du système de suivi utilisé avant de rejoindre la société. J'ai donc essayé de lire le code et de comprendre ce que la classe faisait (pas d'être un statisticien) et j'ai également essayé de déterrer ces rapports de défauts. En l'occurrence, ils étaient assez importants et auraient raccourci la vie du gars suivant pour éditer le fichier sans le savoir assez horrible, car il traitait de problèmes de précision mineurs et de cas spéciaux basés sur des exigences très spécifiques émises par le client d'origine à l'époque. . En bout de ligne, si ceux-ci n'avaient pas été là-dedans, je ne l'aurais pas su. S'ils n'avaient pas été là-bas ET que j'avais eu une meilleure compréhension de la classe,
Parfois, il est difficile de garder une trace d'exigences très anciennes comme celles-ci. En fin de compte, ce que j'ai fait était toujours de supprimer l'en-tête, mais après avoir glissé dans un commentaire de bloc avant chaque fonction incriminante décrivant pourquoi ces calculs "étranges" car ce sont des demandes spécifiques.
Donc, dans ce cas, je les considérais toujours comme une mauvaise pratique, mais mon garçon était heureux que le développeur d'origine les ait au moins insérés! Il aurait mieux valu commenter le code clairement à la place, mais je suppose que c'était mieux que rien.