Est-il considéré comme une mauvaise pratique d'inclure un numéro de bogue dans un nom de méthode pour une solution de contournement temporaire?

Mon collègue qui est un gars senior me bloque sur une révision de code parce qu'il veut que je nomme une méthode 'PerformSqlClient216147Workaround' car c'est une solution de contournement pour un défaut ###. Maintenant, ma proposition de nom de méthode est quelque chose comme PerformRightExpressionCast qui tend à décrire ce que fait réellement la méthode. Ses arguments vont dans le sens de: "Eh bien, cette méthode n'est utilisée que comme solution de contournement dans ce cas, et nulle part ailleurs."

Est-ce que l'inclusion du numéro de bogue à l'intérieur du nom de la méthode pour une solution de contournement temporaire serait considérée comme une mauvaise pratique?

Je ne nommerais pas la méthode comme l'a suggéré votre collègue. Le nom de la méthode doit indiquer ce que fait la méthode. Un nom comme PerformSqlClient216147Workaroundn'indique pas ce qu'il fait. Si quelque chose, utilisez des commentaires qui décrivent la méthode pour mentionner qu'il s'agit d'une solution de contournement. Cela pourrait ressembler à ceci:

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

Je suis d'accord avec MainMa que les numéros de bogues / défauts ne devraient pas apparaître dans le code source lui-même mais plutôt dans les commentaires de contrôle de source car il s'agit de métadonnées, mais ce n'est pas terrible s'ils apparaissent dans les commentaires de code source. Les numéros de bogues / défauts ne doivent jamais être utilisés dans les noms des méthodes.

Rien n'est plus permanent qu'un correctif temporaire qui fonctionne.

Sa suggestion semble-t-elle bonne dans 10 ans? Il était habituel de commenter chaque changement avec le défaut qu'il a corrigé. Plus récemment (comme au cours des 3 dernières décennies), ce style de commentaire est largement accepté comme réduisant la maintenabilité du code - et c'est avec de simples commentaires, pas des noms de méthode.

Ce qu'il propose, c'est une preuve convaincante que vos systèmes de contrôle qualité et d'assurance qualité sont considérablement déficients. Le suivi des défauts et des corrections de défauts appartient au système de suivi des défauts, pas au code source. Le suivi des modifications du code source appartient au système de contrôle des sources. Le référencement croisé entre ces systèmes permet de retracer les défauts jusqu'au code source .....

Le code source est là pour aujourd'hui, pas pour hier et pas pour demain (comme dans, vous ne tapez pas dans la source ce que vous prévoyez de faire l'année prochaine) ...

C'est donc une solution temporaire? Utilisez ensuite le nom suggéré par le réviseur, mais marquez la méthode comme obsolète, de sorte que son utilisation génère un avertissement à chaque fois que quelqu'un compile le code.

Si ce n'est pas le cas, vous pouvez toujours dire que 216147cela n'a aucun sens dans le code, car le code n'est pas lié au système de suivi des bogues (c'est plutôt le système de suivi des bogues qui est lié au contrôle de source). Le code source n'est pas un bon endroit pour les références aux tickets de bogue et aux versions, et si vous devez vraiment y mettre ces références, faites-le dans les commentaires.

Notez que même dans les commentaires, le numéro de bogue seul n'est pas très précieux. Imaginez le commentaire suivant:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Imaginez que le code a été écrit il y a dix ans, que vous venez de rejoindre le projet et que lorsque vous avez demandé où trouver des informations sur le bogue 8247, vos collègues vous ont dit qu'il y avait une liste de bogues sur le site Web du le logiciel du système de rapport, mais le site Web a été refait il y a cinq ans, et la nouvelle liste de bogues a des numéros différents.

Conclusion: vous n'avez aucune idée de ce qu'est ce bug.

Le même code aurait pu être écrit d'une manière légèrement différente:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Vous obtenez maintenant une vision claire du problème. Même s'il semble que le lien hypertexte à la fin du commentaire soit mort il y a cinq ans, cela n'a pas d'importance, car vous pouvez toujours comprendre pourquoi a FindReportsByDateété remplacé par FindReportsByDateOnly.

Je trouve alors PerformSqlClient216147Workaroundplus informatif PerformRightExpressionCast. Il n'y a aucun doute dans le nom de la fonction quant à ce qu'elle fait, pourquoi elle le fait ou comment obtenir plus d'informations à ce sujet. C'est une fonction explicite qui sera super facile à rechercher dans le code source.

Avec un système de suivi des bogues, ce numéro identifie le problème de manière unique et lorsque vous extrayez ce bogue dans le système, il fournit tous les détails dont vous avez besoin. C'est une chose très intelligente à faire dans le code source, et cela fera gagner du temps aux futurs développeurs lorsqu'ils essaieront de comprendre pourquoi une modification a été apportée.

Si vous voyez beaucoup de ces noms de fonction si votre code source, alors le problème n'est pas votre convention de dénomination. Le problème est que vous avez un logiciel buggy.

La suggestion de votre collègue a de la valeur; il offre une traçabilité en associant les modifications au code à la raison, documentée dans la base de données des bogues sous ce numéro de ticket, pourquoi la modification a été effectuée.

Cependant, cela suggère également que la seule raison pour laquelle cette fonction existe est de contourner le bogue. Que, si le problème n'était pas un problème, vous ne voudriez pas que le logiciel fasse cette chose. Je suppose que vous ne voulez que le logiciel pour faire sa chose, de sorte que le nom de la fonction doit expliquer ce qu'il fait et pourquoi le domaine du problème exige que faire; pas pourquoi la base de données de bogues en a besoin. La solution doit ressembler à une partie de l'application, pas à un pansement.

Je pense que vous et lui avez mis tout cela hors de proportion.

Je suis d'accord avec votre argument technique, mais à la fin de la journée, cela ne fera pas beaucoup de différence, surtout s'il s'agit d'un correctif temporaire qui peut être supprimé de la base de code en quelques jours / semaines / mois.

Je pense que vous devriez remettre votre ego dans sa boîte, et laissez-le simplement suivre son propre chemin. (S'il écoutait aussi, je dirais que vous devez faire des compromis. Les deux egos sont de retour dans leurs boîtes.)

Quoi qu'il en soit, vous et lui avez de meilleures choses à faire.

Est-ce que l'inclusion du numéro de bogue à l'intérieur du nom de la méthode pour une solution de contournement temporaire serait considérée comme une mauvaise pratique?

Oui.

Idéalement, votre classe devrait mieux mapper / implémenter un concept dans votre flux / état d'application. Les noms des API de cette classe doivent refléter ce qu'ils font à l'état de la classe, afin que le code client puisse facilement utiliser cette classe (c'est-à-dire ne pas spécifier un nom qui ne signifie littéralement rien à moins que vous ne l'ayez spécifiquement lu).

Si une partie de l'API publique de cette classe dit essentiellement "effectuer l'opération Y décrite dans le document / emplacement X", la capacité des autres à comprendre l'API dépendra de:

1. les sachant quoi chercher dans la documentation externe

2. les sachant où chercher la documentation externe

3. les prenant le temps et les efforts et regardant réellement.

Là encore, le nom de votre méthode ne mentionne même pas où "emplacement X" est pour ce défaut.

Cela suppose simplement (sans raison réaliste) que tous ceux qui ont accès au code ont également accès au système de suivi des défauts et que le système de suivi restera en place aussi longtemps que le code stable existera.

À tout le moins, si vous savez que le défaut sera toujours accessible au même endroit et que cela ne changera pas (comme un numéro de défaut Microsoft qui se trouve à la même URL depuis 15 ans), vous devez fournir un lien vers le problème dans la documentation de l'API.

Même ainsi, il peut y avoir des solutions de contournement pour d'autres défauts, qui affectent plus que l'API d'une classe. Que feras-tu, alors?

Avoir des API avec le même numéro de défaut dans plusieurs classes ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);ne vous dit pas grand-chose et rend le code plus obscur.

Vous pouvez décider que tous les autres défauts sont résolus en utilisant des noms descriptifs de l'opération ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);), sauf dans le cas de votre défaut 216147 (qui rompt le principe de conception du "moins surprenant" - ou si vous voulez le dire de cette façon, il augmente la mesure des "WTF / LOC" de votre code).

TL; DR: Mauvaise pratique! Va dans ta chambre!

Les principaux objectifs d'un programmeur devraient être le code de travail et la clarté de l'expression.

Nommer une méthode de contournement (.... Contournement). Semble atteindre cet objectif. Espérons qu'à un certain stade, le problème sous-jacent sera résolu et la méthode de contournement supprimée.

Pour moi, nommer une méthode après un bogue suggère que le bogue n'est pas résolu ou que la cause racine n'est pas identifiée. En d'autres termes, cela suggère qu'il y a encore une inconnue. Si vous contournez un bogue dans un système tiers, votre solution de contournement est une solution parce que vous connaissez la cause - ils ne peuvent tout simplement pas ou ne le corrigeront pas.

Si une partie de l'interaction avec SqlClient vous oblige à effectuer une conversion d'expression correcte, votre code doit lire "performRightExpressionCast ()". Vous pouvez toujours commenter le code pour expliquer pourquoi.

J'ai passé les 4 dernières années et demie à maintenir des logiciels. L'une des choses qui rend le code déroutant à comprendre lors du saut est le code qui est écrit comme il est uniquement dû à l'histoire. En d'autres termes, ce ne serait pas ainsi que cela fonctionnerait s'il était écrit aujourd'hui. Je ne parle pas de qualité, mais d'un point de vue.

Un de mes collègues a dit un jour: "Lors de la correction d'un défaut, faites en sorte que le code soit tel qu'il aurait dû être." La façon dont j'interprète cela est «Modifiez le code à quoi il ressemblerait si ce bogue n'existait jamais».

Conséquences:

1. En règle générale, moins de code en conséquence.
2. Code simple
3. Moins de références aux bogues dans le code source
4. Moins de risque de régression future (une fois le changement de code entièrement vérifié)
5. Plus facile à analyser car les développeurs n'ont pas à se soucier d'un historique d'apprentissage qui n'est plus pertinent.

Le code source n'a pas besoin de me dire comment il est arrivé à son état actuel. Le contrôle de version peut me dire l'histoire. J'ai besoin que le code source soit simplement dans l'état nécessaire pour fonctionner. Cela dit, un commentaire occasionnel "// bug 12345" n'est pas une mauvaise idée, mais il est abusé.

Donc, lorsque vous décidez de nommer ou non votre méthode 'PerformSqlClient216147Workaround', posez-vous ces questions:

1. Si j'avais eu connaissance du bogue 216147 avant d'écrire le code, comment l'aurais-je géré?
2. Quelle est la solution de contournement? Si quelqu'un qui n'avait jamais vu ce code auparavant le regardait, pourrait-il le suivre? La vérification du système de suivi des bogues est-elle nécessaire pour savoir comment ce code fonctionne?
3. Dans quelle mesure ce code est-il temporaire? D'après mon expérience, les solutions temporaires deviennent généralement permanentes, comme l'indique @mattnz.