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?
comments
issue-tracking
Sanghyun Lee
la source
la source
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:
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.
la 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.
la source
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.
la source
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:
Où le problème 123 décrit à quoi pourrait ressembler cette attaque et pourquoi le nouveau code est à l'abri de l'attaque.
Ou:
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.
la source
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.
la source