Et si oui, où dessinez-vous la ligne? Mes collègues et moi sommes d'accord sur ce sujet. J'ai vu des choses telles que à est-elle OK si la modification est relativement significative et change radicalement quelle était la méthode de la méthode écrit à faire? Ou changez-vous simplement le texte récapitulatif de la méthode pour refléter ce qu'il est maintenant destiné à faire? Mon opinion est que ces informations doivent être placées dans le contrôle de la source. Certains indiquent que cela est mauvais car il sera perdu en dehors du contexte du contrôle de la source (disons que vous changez de systèmes et souhaitez garder des données historiques).
14 Réponses :
Nous avons eu quelques commentaires comme celui-ci, mais notre serveur de Bugzilla est mort et nous avons redémarré au n ° 1 de Bugzilla. Ils sont donc sans signification. Une courte explication du bogue est ma méthode préférée maintenant.
Les commentaires doivent expliquer comment les méthodes fonctionnent.
Le contrôle de la source explique pourquoi les modifications ont été apportées.
En supposant que les commentaires ne soient pas superflus (le classique i ++; // incrément i l'exemple vous vient à l'esprit), il n'y a presque jamais une raison pour discuter contre ajouter un commentaire , peu importe ce que c'est lié à. L'information est utile. Cependant, il est préférable d'être descriptif et concis - ne dites pas "corrige le bug #yy", mais ajoutez plutôt quelque chose comme "Ceci utilisé pour échouer pour x = 0, la logique supplémentaire empêche ici que". De cette façon, une personne qui examine le code peut comprendre pourquoi une section particulière est essentielle à la bonne fonction.
... Mais trop d'informations est utilisée moins et ajoute simplement du bruit.
Par conséquent, le "supposant que les commentaires ne soient pas superflus" introduction. Le commentaire devrait toujours être pertinent pour le code, mais simplement parce qu'un bogue n'est plus présent que cela ne signifiait pas d'avertir les autres de faire de l'erreur à nouveau.
Plutôt que de faire référence à un bogue passé, il ne serait-il pas préférable de dire (pour cet exemple), "Cela empêche une défaillance lorsque x = 0".
Je ne dirais pas que c'est nécessairement "mieux", Steve - l'élément d'information fondamental est présent de toute façon; Et les deux déclarations impliquent qu'une telle affaire doit être payée.
non. Vous devez conserver des informations sur les bogues et le jeu de modifications qui corrige le bogue externe au code source. Toute commentaires dans le code lui-même ne devrait se rapporter qu'à ce que le code fait. Toute autre chose est juste fouillée.
Je pense personnellement que les commentaires devraient porter sur le code lui-même, pas sur une solution de bogue.
Ma raison pour cela est la maintenabilité - 2 (ou 10) ans plus tard, ce commentaire ne sera plus significatif. Dans votre exemple ci-dessus, je préférerais quelque chose comme: La différence est qu'elle n'est pas liée à un bogue , mais plutôt ce que le code est Faire. Les commentaires doivent être commentant au code, pas Meta Info, IMO. Cet avis est partiellement parce que je maintiens une très vieille basebase - et nous avons beaucoup de commentaires qui ne sont plus significatifs liés aux correctifs ou à la fonctionnalité. Demandes d'amélioration, etc ....
Je compte sur Fogbugz et les commentaires d'enregistrement dans SVN. Fonctionne bien, bien que jeffamaphone a déclaré que les numéros de cas n'ont pas de sens si vous perdez votre base de données de bugs.
Un problème de mise en place de commentaires dans le code est que, avec le temps, votre code sera jonché de commentaires sur les problèmes qui n'ont pas existé depuis un moment. En plaçant de tels commentaires dans les commentaires d'enregistrement de la commande source, vous attachez efficacement des informations sur le correctif à la version spécifique où elle a été corrigée, ce qui peut être utile plus tard.
Mon point de vue est que les commentaires devraient être pertinents pour l'intention du développeur ou sur les points forts de «pourquoi» entourant l'algorithme / la méthode.
Les commentaires ne doivent pas entourer un correctif dans le temps.
Ajout d'un commentaire sur la fixation de bugs est une bonne idée, si vous écrivez la bonne chose.
Par exemple, trucs comme corrige le numéro de bogue 22 est mieux conservé dans le contrôle de la source. Les commentaires de votre code doivent être des panneaux de signalisation pour aider les futurs séparateurs sur leur chemin, ne pas satisfaire le processus et le suivi.
+1. Un idéaliste dirait quelque chose comme "les commentaires devraient expliquer comment les méthodes fonctionnent. Le contrôle de la source explique pourquoi les modifications ont été apportées." Cela ignore le fait que lorsque vous lisez un code compliqué, cela aide à savoir pourquoi il fait quelque chose de nonobevieux, et une mention de l'affaire qui a influencé la manière dont il est écrit est aussi bon que tout pour l'expliquer.
Eh bien, cet exemple dit explique comment fonctionne la méthode. avec un peu de contexte historique jeté dans.
D'une fois depuis un moment, vous devez mettre quelque chose dans cela explique pourquoi vous faites quelque chose qui aurait l'air stupide la plupart du temps.
Je conviens que ces données doivent être placées dans le contrôle de la source ou une autre gestion de la configuration de la pièce. Après avoir travaillé dans des codesbases qui placent des informations sur les corrections de bugs dans des commentaires, je peux dire que cela conduit à des commentaires et de code très encombrés plus tard. Six mois après le correctif est en place, voulez-vous vraiment savoir que sur une ligne de fixation d'un bug de longue date? Que faites-vous avec les commentaires lorsque vous devez refacturer le code?
quelque chose comme // fixe bug # 22
n'a pas de sens à lui seul et nécessite des étapes supplémentaires pour même avoir une idée de ce que cela signifie et quel rôle il remplit. Une brève description est à mon avis plus appropriée, quel que soit le logiciel de suivi des bogues ou de contrôle source que vous utilisez peut utiliser.
Si l'algorithme doit être codé d'une certaine manière - de contourner un bogue dans une API tiers Par exemple, cela devrait être commenté dans le code de sorte que la personne suivante qui vienne n'essaye pas de "optimiser "Le code (ou autre) et réintroduire un problème.
Si cela implique l'ajout d'un commentaire lorsque vous réparez le bug d'origine, faites-le.
Il servira également de marqueur afin que vous puissiez trouver le code dont vous avez besoin pour vérifier si vous avez toujours mis à niveau vers la prochaine version de l'API.
Nous utilisons l'équipe Foundation Server pour le contrôle de source ici chez My Société et vous permet d'établir un enregistrement dans un rapport de bogue, donc je ne mettrais donc pas un commentaire directement dans le code au serveur au même but.
Cependant, , dans des situations où je suis implémentant du code comme solution de contournement pour un bogue dans la tramette .NET ou une bibliothèque tierce, j'aime mettre l'URL au journal Microsoft Techet ou Site Web décrivant le bogue et son statut.
Droit - un lien vers un bug ouvert est quelque chose de différent.
évidemment
// Treat this as a bleet. Misnomed grotzjammers and particle
// bleets are actually both special cases of the same
// situation; see Anna's analysis in bug #22.
i++;
Une autre prise: les numéros de bogue sont des hyperliens. Le code actuel et les vieux bugs ne sont souvent pas liés, mais parfois ils sont et un lien est approprié.
Dans le référentiel source PERL5, il est courant de faire référence à des bogues, avec leur numéro de trac associé dans les fichiers de test.
Cela donne plus de sens pour moi, car l'ajout d'un test d'un bogue empêchera que le bogue soit à nouveau inaperçu.