Commentaires sur le numéro de bug

StackOverflow https://stackoverflow.com/questions/163232

  •  03-07-2019
  •  | 
  •  

Question

Pourquoi voudriez-vous ajouter

  

// Bug 1024

commente-t-il dans une base de code contrôlée par le code source? La plupart des systèmes de suivi des bogues et de contrôle des sources sont mieux équipés pour suivre ces informations. En contrôle de source, une étiquette ou un commentaire peut être utilisé avec l'archivage. Dans un suivi de bogues, le numéro de révision peut être ajouté à la résolution du bogue. Alors pourquoi commenter le code? En particulier parce que la pertinence de ces commentaires est de très courte durée et qu'ils ont tendance à s'accumuler dans la base de code.

Était-ce utile?

La solution

J'ai trouvé l'un d'entre eux utile l'autre jour dans notre base de code.

J'ai dit "Pourquoi appelle-t-il la fonction d'initialisation une deuxième fois, si tard dans le flux de travail?"

Le commentaire de bogue m'a laissé aller à la description du problème. Lorsque j'ai réorganisé le code, j'étais sûr d'inclure ce bogue dans mes tests et je ne l'ai pas réintroduit.

Bien que je dirai qu'en général, je suis d'accord avec vous et ne les insérez pas moi-même.

J'aurais préféré que le développeur en question corrige le bogue de manière plus significative, afin que je ne m'interroge pas sur le code.

Autres conseils

En fin de compte, je pense que c'est une mauvaise pratique. Il est préférable d’inclure pourquoi le bogue existe (les foos de type Y n’ont pas la propriété Z). Vous pouvez inclure un "plus dans l'ID de bogue 12345". avec cela si vous voulez.

Si vous intégrez plusieurs niveaux, une vue de code source dans trac peut être directement reliée à l'ID de bogue.

Paresse pure. Bien sûr, cela prend plus de temps à long terme, mais à court terme "// Bug 1024". ne demande aucun effort. Plus vous avez de code, plus c'est pire.

Imaginez que vous ayez détecté un nouveau bogue qui a entraîné le changement dans la révision 12345. Vous consultez les journaux et il vous dit immédiatement que le bogue 1024 était la raison pour laquelle le changement a été effectué.

Vous pouvez ensuite consulter 1024 pour voir quoi, pourquoi et quand avant de créer un nouveau correctif, celui qui les gouvernera tous.

Si le numéro de bogue ne figure pas dans le message de validation, vous devez alors rechercher le bogue corrigé par une validation, qui peut être plusieurs (si le bogue est signalé plus d'une fois).

Je pense que c’est un cas de "j’ai un marteau, ce doit être un clou". Votre éditeur de texte ou votre IDE n’est pas votre seul outil de gestion du code.

L’historique est mieux conservé en externe par rapport au code. La signification du code doit être décrite dans les commentaires lorsque cela n’est pas immédiatement évident.

Je conviens que les numéros de bogues doivent figurer dans les messages de validation du contrôle de code source.

Vous ne devez jamais ajouter uniquement le numéro du bogue. Vous devez ajouter le numéro et le sujet du bogue, ainsi que tous les qualificateurs, si vous avez effectué plusieurs archivages pour un seul bogue:

Bug 1111 - Foo a échoué sur des systèmes 64 bits. Correction n ° 2 car elle a été rouverte après la fusion avec le tronc.

Certains systèmes intègrent un numéro de bogue. Dans mxr.mozilla.org, le numéro de bogue affiché dans le journal cvs est automatiquement transformé en lien vers le numéro bugzilla.mozilla.org. Lorsque vous creusez dans le code, vous gagnez un temps considérable. Je pense que Fogbugz a une caractéristique similaire ...

De plus, même si votre système ne le fait pas, cela aide souvent car personne ne veut voir tout le contexte du changement dans les commentaires, c'est à cela que le suivi des bogues est destiné.

Je conviens avec vous que ce commentaire n’est pas vraiment utile et est trop bref.

Il est cependant extrêmement utile et important de commenter le code avec des références aux enregistrements dans le système de suivi des défauts (ou à celui-ci à tout référentiel KM que vous pourriez avoir).

Parfois, un code est modifié pour implémenter une solution de contournement à un problème spécifique lié au comportement de l'application. Parfois, la solution de contournement introduite n’est en aucun cas logique. Il arrive souvent que lorsqu'un code est mis à jour par quelqu'un d'autre, ce «mauvais» élément de code soit supprimé dans le cadre d'un effort de re-factorisation.

Ainsi, marquer un code comme appartenant à un correctif de bogue particulier le rend visible lors de la refactorisation, invitant le développeur à revoir la description du bogue avant de modifier le code. Cela aide également dans les cas où le bogue est rouvert: si vous devez modifier plusieurs fois la même partie du code, vous pouvez envisager d'investir du temps dans une solution alternative.

P.S. cet article sur MS Office de Joel On Software est utile. Autant que je sache, le code de MS Office et de MS Windows regorge de commentaires similaires expliquant les décisions prises par les développeurs depuis longtemps.

Je trouve cela utile d’expliquer du code qui semblerait autrement erroné, ainsi que pour une utilisation dans les messages de validation.

Je ne fais pas ça. Je ne peux pas penser à une bonne raison pour laquelle vous mettriez l'ID de défaut dans le code. Je vais mettre cela sur les notes de publication / changelog à la place.

Ce que je trouve utile, c’est d’utiliser l’identifiant de défaut dans le nom des tests automatisés: 

[TestFixture]
public class Release_1_2_Bugfixes
{
  [Test]
  public void TestBug42()
  {
    Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything());
  }
}

J'ai consulté d'autres projets faire la même chose.

Je suis surpris de voir combien de personnes s’opposent à cela. Mon sentiment personnel à ce sujet est qu’il s’agit d’une bonne bonne idée. Je suis d'accord avec un commentaire précédent selon lequel il devrait inclure plus que le numéro de bogue, et inclure de préférence un court résumé et un lien vers le système de suivi des bogues si nécessaire.

Les avantages de ces commentaires ne sont évidents que dans un projet plus ancien comportant un historique et un grand nombre de corrections de bugs antérieures. Vous n'avez pas à faire ces commentaires partout, mais ils sont vraiment très utiles lorsqu'ils sont placés devant un bloc de code qui pourrait ne pas avoir de sens sans contexte. Dans tout type de système raisonnablement complexe, il y aura des fragments de code qui semblent illogiques ou inutiles sans contexte.

En raison d'interactions avec le système ou d'anciennes solutions de contournement, le code est nécessaire. Pour éviter que quelqu'un réintroduise plus tard un bogue corrigé, il est extrêmement utile d'indiquer le bogue que le bloc de code est conçu pour corriger, de préférence avec une explication jointe. Sinon, vous comptez sur une personne qui vérifie attentivement l'historique de validation pour une raison consignée dans le journal de validation, ce qui est hautement improbable, notamment si quelqu'un code du refactoring.

MODIFIER : je fais spécifiquement référence à ceux-ci avec un bloc de code inhabituel ou nécessitant un contexte supplémentaire. Il n'est ni utile ni nécessaire de commenter chaque correction typographique que vous apportez: -)

Je l’ai fait jusqu’à Visual Studio 2008, avec annotation. Lorsqu’on regarde l’ancien code, il est utile de constater immédiatement qu’au moins une décision de code a été prise.

Oui, je sais que vous pouvez faire la comparaison avec les versions précédentes, mais c’est vraiment pénible lorsque vous avez juste besoin de vous sentir bien à propos des mises à jour mineures du code.

Si vous parcourez un code source inconnu et que vous voyez quelque chose d’évident, il est agréable de connaître la raison. C’est toutefois un jugement, toutes les corrections de bugs n’ont pas besoin d’une telle explication - la plupart d'entre elles peuvent probablement s'en passer.

S'il y a suffisamment de raisons de croire que quelqu'un voudrait connaître le numéro du bogue lors de la lecture d'une partie du code, il peut être très agréable d'ajouter un commentaire mentionnant le bogue (j'espère que cela paraphrasera les éléments importants du bogue, cependant).

Oui, les messages de validation du contrôle de source doivent également contenir les numéros de bogues, et consulter les journaux de révision peut vous donner les mêmes informations ... mais si la même partie du code est modifiée plusieurs fois, mais les détails appris à partir du Le bogue initial s’applique toujours, cela peut prendre un certain temps avant de trouver le changement original pour en savoir plus sur ce bogue.

De même, il peut arriver qu’il existe une bonne raison de déplacer le code d’une classe à une autre ou de renommer des fichiers, ce qui compliquerait encore la recherche de la raison de la raison derrière une certaine section de code (renommer problème avec SVN, mais une douleur avec CVS).

Vous avez frappé le clou avec la "pertinence" qui a duré très peu de temps et ils ont tendance à s'accumuler dans la base de code. "

Chaque brouillon inutile accumulé dans les fichiers source les rend un peu moins lisibles et difficiles à gérer. Supprimer tout ce qui n'ajoute pas de valeur. "Bug 12345" a peu de valeur maintenant et n'en aura plus dans quelques semaines.

Nous travaillons sur un système à grande échelle avec de nombreux développeurs et plusieurs branches publiées.

Ces commentaires sur les bogues peuvent être très utiles lors du transfert d’une branche à une autre, d’autant plus que le système SCM que nous utilisons est très pauvre en fonctionnalités et que les commentaires de validation sont difficiles à obtenir ou peuvent être très anciens.

Si le correctif était simple, il n’aurait peut-être pas besoin d’un marqueur de bogue. Si cela n’est pas évident, il peut être plus judicieux de faire référence à un bogue, puis d’écrire une longue explication dans une section de commentaire.

Je n'aime pas ce genre de graffiti. Comme d’autres formes de vie désagréables qu’ils accumulent avec le temps, ils étouffent la base de code.

Le problème commence vraiment lorsque les gens corrigent un bogue qui chevauchait un correctif précédent. Vous avez alors des numéros de bogues étiquetant une section de code qui sont simplement faux ou trompeurs.

Ce type de commentaire EST très utile: que se passe-t-il lorsque vous modifiez les outils de suivi des bogues ou de contrôle de source? Une référence à BZ1722 vs FB3101 vous indiquerait quel outil de suivi vérifier (Bugzilla ou FogBugz par exemple).

C'est une bonne chose!

La personne qui consulte le code a peu de chances d’apprécier l’historique complet du code et annulera probablement un changement très important car elle n’a peut-être jamais travaillé dans ce domaine du code. Cela peut expliquer un code qui semble autrement insensé ou une exigence client équivalente.

Vous ne pouvez pas toujours capturer dans les moindres détails les exigences des clients à travers l’architecture et le code, surtout quand ils demandent quelque chose de stupide. Par conséquent, vous commencez avec le sensible, puis affinez ou hackez le code en stupide lorsque vous êtes obligé de le faire, les numéros de bogues sauvegardent l’intention du code fou.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top