J'ai vu de nombreux numéros de problème à partir des commentaires du code jQuery . (En fait, il y avait 69 numéros de problème dans le code jQuery.) Je pense que ce serait une bonne pratique, mais je n'ai jamais vu de directives.
S'il s'agit d'une bonne pratique, quelles sont les lignes directrices de cette pratique?
Réponses:
En général, je ne considérerais pas cela comme une bonne pratique. Mais dans des cas exceptionnels, cela peut être très utile, à savoir lorsque le code doit faire quelque chose d'inintuitif pour résoudre un problème complexe, et sans aucune explication, il y aurait un risque que quelqu'un veuille «corriger» cet étrange code et ainsi le casser , tout en expliquant le raisonnement entraînerait un énorme commentaire qui duplique les informations du problème.
Je pense qu'il suffit d'ajouter le numéro de problème au message de validation lorsque vous validez le correctif associé à votre système de contrôle de source.
Par exemple:
Bogue n ° 203: les connexions à la base de données n'expirent plus après 30 secondes.
Je trouve que l'ajout de numéros de problème, de noms de développeurs ou de dates auxquelles des modifications ont été apportées dans le code pollue simplement la base de code et devrait vraiment être géré en externe par votre système de contrôle de source.
Je suis complètement en désaccord avec les autres affiches ici!
Les commentaires de code avec des références de suivi peuvent être d'une grande aide pour la programmation de la maintenance.
Si je recherche un bogue et que je me rapproche de la zone du code, voir qu'il a récemment été modifié et avoir un lien vers le contexte du changement est un envoi de Dieu.
Oui, nous avons le contrôle du code source, mais il peut être assez lent de vérifier les fichiers et les modules individuellement. Tu veux ces choses vous sautent aux yeux pour les changements récents.
Je les déprécierais probablement car je vois des très anciens dans la base de code, mais il y a très peu d'inconvénients à conserver les plus récents et beaucoup de temps de développeur potentiellement économisé si vous les utilisez intelligemment.
En fait, je pense que ces petites références à votre système de suivi des bogues sont préférables aux commentaires détaillés dans le code.
git gui blame <filename>fournit une interface graphique très rapide pour parcourir l'historique du code si vous utilisez git. L'utilisation d'un outil pour combiner les commentaires de code avec l'historique permet une documentation du code bien meilleure que tous les commentaires en ligne. Autrement dit, si vous vous embêtez à écrire de bons messages de validation (un bon message de validation doit être à peu près égal à un e-mail expliquant pourquoi ce correctif doit être appliqué).
Si vous souscrivez à une politique de «code propre», vous devrez probablement vous demander s'il est judicieux d'ajouter des commentaires. Si le code ne peut être clarifié qu'avec un commentaire, alors bien sûr, ajoutez-en un, sinon vous devriez être en mesure de comprendre facilement ce que fait votre code simplement en le lisant (à condition d'utiliser des noms sensés pour vos variables, méthodes, etc.).
Quelle que soit votre opinion personnelle sur la question de savoir si le commentaire est une bonne pratique ou non, un commentaire doit contenir des informations qui ont une valeur directe pour le code auquel le commentaire fait référence. Dans ce cas, la question est de savoir si l'ajout d'un numéro de problème ajoute de la valeur au code. Le problème que je vois avec l'ajout du numéro de problème est que vous pouvez avoir une section de code qui pourrait être fortement modifiée afin de satisfaire plusieurs problèmes, et après un certain temps, il pourrait être impossible d'identifier correctement les changements liés à un problème spécifique. Les problèmes ultérieurs, par exemple, peuvent nécessiter une refactorisation importante du code relatif aux problèmes antérieurs. C'est peut-être un exemple extrême, mais cela montre comment les numéros de problème dans les commentaires dans le code peuvent s'avérer assez inutiles.
Si vous pouviez garantir que la situation que je viens de décrire ne se produirait jamais, je dirais toujours que le numéro de problème lui-même est encore assez inutile sans une description de ce qu'est le problème, et pourtant, toutes ces informations appartiennent vraiment à votre système de suivi des problèmes et doit être dupliqué. Un meilleur endroit pour noter le numéro du problème serait dans votre système de contrôle de version en tant que commentaire de validation. L'avantage est que vous pouvez comparer les versions et voir les modifications de code relatives à un problème spécifique, tandis que le numéro de problème lui-même vous fournit l'identifiant nécessaire si vous souhaitez examiner la raison du changement de code.
Avec tout cela à l'esprit, je suggère que ce n'est pas vraiment une bonne pratique en tant que telle d'ajouter des numéros de problème dans les commentaires dans votre code.
Je pense que c'est une bonne pratique de se référer à un problème pour une lecture plus approfondie, tout en donnant une brève explication dans le commentaire lui-même.
J'ajoute généralement des commentaires uniquement s'il y a quelque chose de subtil ou d'intuitif dans ce morceau de code. Étant donné que certains problèmes subtils ne peuvent pas être expliqués complètement en quelques lignes et que je ne veux pas ajouter des dizaines de lignes de commentaires, j'ajouterais un bref commentaire décrivant ce que cela tente d'atteindre, et je renvoie au problème pour détails.
Par exemple:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
Où le problème 123 décrit à quoi pourrait ressembler cette attaque et pourquoi le nouveau code est à l'abri de l'attaque.
Ou:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
Le principal problème avec la mise des numéros de problème dans votre source est que vous avez maintenant une référence externe. Vous devez donc être sûr de ne pas perdre le problème.
L'inclusion du numéro de problème dans les messages de validation peut être très utile lorsque votre code source est connecté avec une intégration continue. Des applications comme TeamCity vont extraire ces informations et permettre de meilleurs rapports.
Cela dit, je ne suis pas sûr à 100% qu'il tire des commentaires du code. L'inclusion de numéros de problème dans le code fonctionne bien si les numéros de problème sont persistants (par exemple, vous ne modifiez pas les suiveurs de problèmes) et que vous n'avez pas beaucoup de problèmes pour un projet donné.
Il est probablement plus utile de décrire le problème et la solution afin que le prochain développeur n'ait pas besoin de rechercher le numéro du problème. Le compilateur ou le minifieur supprimera simplement vos commentaires avant que le code ne soit libéré dans la nature, donc il ne devrait y avoir aucun impact sur le résultat final.