Nunit: Meilleures pratiques pour les commentaires de documents XML

Ça sonne bien - tout pour mettre en place une norme. Il y a pas mal de xmldoc incorrect qui pourrait également être corrigé. (Paramètres erronés, etc.)

Je suppose que vous envisagez de restreindre tout ce qui précède aux seuls types de public?

@ChrisMaddock

Je suppose que vous envisagez de restreindre tout ce qui précède aux seuls types de public?

Bon point. C'est la motivation et la première urgence, même si je pense que lorsque nous écrivons du code, nous devrions au moins envisager de le suivre pour les types internes également au cas par cas. Cela aiderait certainement à se mettre à jour en examinant les PR. Je ne sais pas ce que les autres pensent.

Je voterais contre l'ajout de beaucoup plus à nos normes de codage. Les normes de codage devraient être minimales et inclure uniquement les choses que nous sommes prêts à imposer à tout le monde. Si nous spécifions des périodes, alors je pense que nous devenons trop détaillés.

Je dis souvent aux équipes de penser à la norme de codage comme s'il s'agissait du patron - c'est-à-dire, aimeriez-vous que votre patron vous dise continuellement de faire cette chose. Dans une équipe autonome, la norme de codage n'est bien sûr pas un patron. L'équipe est le patron et __rien__ ne devrait figurer dans la norme de codage à moins que l'équipe ne l'approuve réellement. Ne mettez pas de choses et dites que nous pouvons faire une exception - mettez simplement des choses pour lesquelles vous ne ferez aucune exception.

Tout cela vient d'un point de vue particulier, bien sûr. Quarante ans dans l'industrie dont les 15 derniers en tant que coach, travaillant avec des équipes pour mettre en place des pratiques XP, y compris des normes de codage. Je n'ai jamais trouvé de norme de codage dans la nature qui ne puisse être raccourcie. Ils incluent presque toujours des choses dont personne ne se soucie vraiment assez. Faire la norme de codage sur la façon d'écrire un code minimalement acceptable, pas un code parfait. IOW, si vous mettez des points dans la norme de codage, cela devrait signifier que vous envisagez de rejeter les PR faute de point et cela me semble idiot.

@jnm2 Vous avez fait en sorte que cela s'applique au framework uniquement en le mettant ici. Est-ce votre intention?

De plus, en ce qui concerne les commentaires XML, ils ne sont pas du tout requis sur les types publics, sauf si nous parlons d'un assembly qui les requiert. Toutes nos assemblées ne le font pas.

Oui, je pense que le polissage des types destinés au public de NUnit est suffisamment important pour que je demande des modifications sur tout PR qui n'inclut pas de point, comme je l'ai fait. C'est la norme minimale que je considère personnellement aussi importante pour le professionnalisme que de demander qu'une faute de frappe soit corrigée.

Et oui, cadre uniquement. Le framework est le seul endroit où les utilisateurs finaux voient la documentation XML, n'est-ce pas ?

@jnm2 Je suppose que j'aurais pu dire d'abord que j'aime tous vos points si vous parlez d'un guide sur la façon d'écrire de bons commentaires XML. Mais vous avez parlé de norme de codage, qui est un ensemble d'exigences obligatoires, et c'est ce sur quoi je me concentrais.

@jnm2 OK, je vérifie juste le framework.

Voici mon point de vue sur ce que signifie une norme de codage ...

Si vous voulez un point à la fin de chaque phrase, vous pouvez le demander, que la norme de codage le dise ou non. C'est comme ça qu'on fait presque tout. Les programmeurs peuvent suivre vos conseils ou non, mais surtout les suivre. C'est le niveau d'autorité que j'ai eu en tant qu'entraîneur pendant quinze ans. Les gens ont fait ce que j'ai suggéré parce qu'ils ont respecté mon opinion. Les gens feront de même lorsque vous réviserez leur code, avec ou sans norme de codage pour vous donner l'autorité.

OTOH, si c'est dans la norme de codage, vous ou quelqu'un d'autre pouvez __exiger__ que la période soit ajoutée. Une norme de codage n'est pas un ensemble de suggestions ou de lignes directrices, mais un ensemble d'exigences assez arbitraires. C'est particulièrement bien pour les choses qui peuvent aller dans un sens ou dans l'autre, mais pour lesquelles nous voulons standardiser, comme les conventions de nommage. C'est pourquoi je dis qu'une norme de codage devrait être minimale dans toute équipe autonome. De toute évidence, cela est totalement différent de toutes les normes d'entreprise qui sont transmises d'en haut.

Pour clarifier d'où je viens, une bonne documentation XML publique et des messages d'exception sans désinformation, mauvaise grammaire ou fautes d'orthographe ne sont pas moins importants de mon point de vue qu'une bonne implémentation sans bogues ni négligence excessive. Tout comme je ne considérerais pas comme acceptable d'avoir des tests défaillants et un code bogué dans le maître, je ne considérerais pas comme acceptable d'avoir une mauvaise documentation XML.

Je suis généralement d'accord avec vous sur les normes de codage. C'est un très bon point que j'aime tellement que je continue d'espérer qu'une conversation se lève où je puisse être d'accord avec vous sur son application ! 😃 Cela me fait réaliser que la documentation XML (et les messages d'erreur) sont uniques par rapport à toutes les autres normes de codage. C'est presque un produit distinct de la mise en œuvre. Personnellement, je serais heureux d'appliquer un invariant pour atteindre l'objectif d'une documentation XML professionnelle destinée à l'utilisateur exactement de la même manière que nous appliquons des invariants de test sur l'implémentation.

Mais ce n'est que mon vote. Je suis intéressé par votre réaction et celle du reste de l'équipe à l'idée. Avez-vous une vision d'une sorte de barre à long terme à définir pour la qualité de la documentation XML ? Quelle serait la hauteur de la barre ? Vaut-il mieux rester comme nous sommes sans bar à long terme ?

Je suppose que j'aurais pu dire d'abord que j'aime tous vos points si vous parlez d'un guide sur la façon d'écrire de bons commentaires XML. Mais vous avez parlé de norme de codage, qui est un ensemble d'exigences obligatoires, et c'est ce sur quoi je me concentrais.

Un facteur de plus. Les contributeurs recherchent les normes à suivre. Je le fais, je vois des preuves que d'autres le font. Ils examinent généralement la norme de codage et les fichiers à proximité pour décider de la marche à suivre. Nous devrions avoir un moyen de documenter les recommandations à suivre à la discrétion du contributeur même si nous ne souhaitons pas en faire une norme de codage.

@jnm2

"Une bonne documentation XML publique et des messages d'exception sans désinformation, mauvaise grammaire ou fautes d'orthographe ne sont pas moins importants de mon point de vue qu'une bonne implémentation sans bogues ni négligence excessive. code dans master, je ne considérerais pas qu'il soit acceptable d'avoir une mauvaise documentation XML."

<chiding>
Je suis désolé, mais je dois t'appeler là-dessus. C'est une erreur de supposer que quiconque n'est pas d'accord avec vous ne doit pas partager vos valeurs de bon travail. C'est en fait tout l'argument que j'essaie de faire valoir au sujet des normes. Si l'on écrit une norme qui dit « les documents doivent avoir des mots correctement orthographiés », par exemple, on n'énonce pas seulement l'évidence mais on insulte les autres membres de l'équipe. C'est exactement le genre de norme que j'ai trouvée dans de nombreux corps, où une organisation distincte a créé des politiques et des procédures que les programmeurs doivent suivre. Tout comme nous n'écrivons pas un standard qui dit "les programmes C# doivent être correctement écrits et suivre de bons principes d'organisation", nous ne voulons pas d'un standard qui dise la même chose à propos de la documentation XML.

Notre désaccord n'est pas sur la documentation ou sa valeur ou sur la fabrication en général. Il s'agit de la nature et de l'objectif d'une norme de codage.

Suggérer que celui qui n'est pas d'accord avec vous accorde moins d'importance à la qualité de l'exécution que vous est un argument ad hominem de la pire espèce.
</chiding>

Désolé pour ça. ??

Le terme "Coding Standard" (en majuscules) est un terme technique dans la plupart des développements agiles et certainement dans XP. Cela ne signifie __pas__ aucune des choses que je vois suggérées comme objectif de cette norme de codage. La norme de codage que nous avons a été écrite, principalement par moi, en utilisant le sens XP du terme. Vous pourriez changer cela, mais comme il y a beaucoup d'autres mots, j'espère que vous ne le ferez pas.

Ce que vous décrivez est (à mon avis) plutôt des « meilleures pratiques dans la documentation XML », alors qu'une norme de codage est (dans ma définition) plutôt des « pratiques minimales ». Cela n'aurait pas d'importance, sauf que je pense que nous avons en fait besoin de quelque chose qui décrit un strict minimum la plupart du temps.

Par exemple, une grande partie de ce qui est fait sur NUnit est fait par des contributeurs occasionnels. Maintenant, si nous renvoyons les gens alors qu'ils n'ont pas suivi toutes vos bonnes pratiques, alors ils ne reviendront peut-être pas et nous aurons moins de contributeurs. OTOH, si nous acceptons leur travail et travaillons ensuite à l'améliorer ainsi qu'à les amener à faire mieux la prochaine fois, nous aurons de meilleures chances de les retenir.

Enfin, je dois ajouter ceci : __si__ vos idées sont si bonnes, pourquoi avez-vous besoin de la force de l'autorité « juridique » derrière elles ? 😸 Personnellement, je ne pense pas que vous le fassiez.

Notre norme la plus élevée est que nous ne fusionnerons rien à moins que deux commiteurs ne l'acceptent. Tout le reste est enseignement, pas application.

C'est une erreur de supposer que quiconque n'est pas d'accord avec vous ne doit pas partager vos valeurs de bon travail.

Je suis désolé! Pas du tout l'implication que je voulais. Je suis d'accord avec ce que tu dis.

Voici ce que j'essaie d'apprendre. Si nous finissons tous par convenir que nous voulons être dans un endroit où chaque phrase de documentation XML a une marque de fin parce que nous pensons que c'est une meilleure expérience client, alors nous devons choisir comment nous y arriverons :

• Nous pourrions repérer et demander des changements dans les PR.
• Nous pourrions revoir le code de base pour le corriger nous-mêmes périodiquement.
• Nous pourrions écrire un test qui le vérifie et avertit ou fait des erreurs. (Cela fait gagner du temps au contributeur et nous évite de manquer des choses.)
• Nous pourrions l'ajouter à une norme de codage si nous ne sommes pas disposés à expédier sans que _quelqu'un_ corrige le style ou un document sur les meilleures pratiques si nous le sommes. (Cela permet au contributeur de gagner du temps lorsqu'il recherche des conseils. Peut se traduire par une documentation XML de meilleure qualité que nous ne serions à l'aise de tenir un PR.)

Donc, si j'ai demandé plus clairement, qu'est-ce que j'oublie ?

Maintenant, si nous renvoyons les gens alors qu'ils n'ont pas suivi toutes vos bonnes pratiques, alors ils ne reviendront peut-être pas et nous aurons moins de contributeurs.

J'envisageais de demander des modifications sur les PR, mais je ne suis pas sûr de comprendre ce que vous voulez dire ici. À quoi ressemble le renvoi des gens ?

Peut-être y a-t-il une sorte de fossé entre la façon dont nos normes de codage sont actuellement utilisées et ce que nous voulons qu'elles soient. Je viens de faire un petit tour maintenant - il y a des morceaux là-dedans que je ne connaissais pas, et que je n'aurais jamais appliqués en révision, ni même écrits dans mon propre code ! ??

Mes pensées:

• Un document fournissant des directives sur le format xmldoc sonne bien - exactement ce que nous appelons ce document, je ne suis pas trop inquiet !
  
  
  
  • Je me méfierais également de renvoyer des gens juste pour corriger quelques points sur un PR. Cependant, d'autres projets fonctionnent comme ça (Cake) - et cela semble fonctionner assez bien pour eux.
  
  
  • J'espère également qu'une fois que le xmldoc existant sera plus standardisé, les gens seront en mesure de comprendre les conventions, et ce qui précède peut ne pas être un problème si courant.
  
  

Je me méfierais également de renvoyer des gens juste pour corriger quelques points sur un PR.

Si le contributeur la voit de la même manière qu'une faute de frappe, via des directives ou en voyant ce que font les fichiers à proximité, il est possible qu'il soit même impatient de la corriger. Ça dépend, c'est comme ça qu'on veut le voir et le présenter ?

Je suis d'accord avec @CharliePoole. Moins c'est mieux !

En fait, je n'aime pas l'exigence de période. Je pense que ça encombre les choses. Je n'ai jamais utilisé de points dans mes commentaires XML. Personne ne s'est jamais plaint d'un projet auquel j'ai participé.

Merci pour ce retour, @oznetmaster.

Nous pourrions:

• Ne rien faire (je demanderai peut-être des marques de fin sur les phrases... 😈)
• Décidez qu'il est acceptable pour NUnit d'avoir des styles mélangés dans sa documentation XML (j'arrête de demander de tels changements)
• Décidons que nous voulons l'un ou l'autre style

@jnm2 Recommencer ! Je __seulement__ en désaccord avec __deux__ mots de votre proposition initiale : "Norme de codage". En fait, je suis d'accord avec presque tout le reste - j'évite d'encombrer cette discussion avec les détails pour le moment.

J'aurais peut-être dû vous répondre initialement en disant "Merci. Je suis d'accord avec la plupart de cela. Je pense que c'est mieux comme document d'orientation comme "Meilleures pratiques pour les commentaires de document XML" plutôt qu'une norme de codage. Il y a de fortes chances que nous l'aurions réglé plus rapidement .

Récapitulons : Mon parcours, du moins la partie dont je suis le plus fier, est celui d'un gars XP. Dans XP, "Coding Standard" a une signification spécifique, qui n'est peut-être pas ce que cela signifie pour vous. C'est un amas de trucs un peu insignifiants sur lesquels on s'installe une bonne fois pour toutes pour ne pas passer tout notre temps à se disputer. Des trucs comme le placement d'accolades, s'il faut utiliser un préfixe sur les champs de membre, etc.

La plupart des experts que je respecte disent que vous __ne faites pas__ les meilleures pratiques dans une norme de codage. Vous permettez à l'équipe de faire évoluer ses propres bonnes pratiques. Plusieurs fois, il existe plusieurs « meilleures » (ou sacrément bonnes) pratiques et il n’est en fait pas nécessaire de choisir entre elles une fois pour toutes. C'est ce qu'on appelle "Faire confiance aux gens sur les politiques et les procédures."

Ce n'est que mon parcours, et probablement pas le vôtre. Dans le passé, j'ai pu imposer mes convictions personnelles sur ce projet. Sous peu, je ne pourrai plus le faire. C'est pourquoi nous essayons de mettre en place un modèle de gouvernance. Mais penser à la façon dont nous gérons les choses ne signifie __pas__ pour moi que nous voulons avoir plus de politiques et de procédures. Il s'agit davantage de la façon dont nous résolvons une question lorsqu'il y a plusieurs opinions.

Mais comme je l'ai dit, je ne pense pas que nous soyons si éloignés, mais nous nous concentrons simplement sur des choses différentes. Quand vous dites Coding Standard, j'entends quelque chose qui doit absolument être suivi - il n'y a pas de jugement. Je veux que ce soit minime parce que je __veux__ que les gens fassent preuve de jugement. Si nous avons un ensemble de pratiques exemplaires ou recommandées, la plupart des gens utiliseront leur jugement en les suivant. En fin de compte, les personnes qui passent le plus de temps dans le code "gagneront" en faisant les choses comme elles pensent qu'elles devraient être - et c'est comme cela devrait être en open source.

Habituellement, un élément d'un commentaire XML est une seule "phrase".

Sinon, j'utilise généralement l'élément para pour chaque "phrase".

@jnm2 Il me semble que la chose logique à faire est que vous

Je pense que même essayer d'écrire les "meilleures pratiques" pour la documentation XML pourrait être une pente glissante.

Immédiatement, cela soulève des questions comme « quel anglais vérifions-nous l'orthographe » ? Quelle culture utilisons-nous pour les chiffres et pour les séparateurs de liste ? Un espace ou deux après un point (si nous autorisons/exigeons des points).

Je pense vraiment que c'est un peu loin de l'endroit où nous devrions concentrer nos attentions !

Existe-t-il une norme de codage ou des pratiques exemplaires pour les pages de documentation ?

@CharliePoole D'accord, je pense que nous sommes sur la même

@oznetmaster Je pense que ces questions sont hors de portée de la documentation XML, du moins pour le moment. Et si l'équipe du framework NUnit est parvenue d'une manière ou d'une autre à un consensus sur la nécessité de formater les listes d'une certaine manière, pourquoi serait-ce une mauvaise chose ? C'est vraiment à l'équipe?

Je ne vois pas pourquoi ils sont hors de portée. Ils sont aussi pertinents que la ponctuation d'une phrase.

Est-ce que « couleur » doit être orthographié couleur ou couleur dans la documentation ? Un séparateur de chiffres dans un nombre doit-il être une virgule ou un point ? Idem pour le séparateur décimal. La liste "a, b, c, d" s'écrit "a; b; c; d" en Allemagne.

Je pense que votre postulat est que la documentation XML pour le côté public du framework doit être cohérente, car c'est ainsi que les utilisateurs de NUnit "voient" le plus souvent NUnit. Cela fait partie de la cohérence.

@oznetmaster Je pense que la réponse à vos questions est, attendons que quelqu'un s'en soucie et partons de là.
Je ne vois pas comment « couleur » par rapport à « couleur » affecte l'expérience de l'utilisateur final, mais l'équipe peut certainement avoir cette conversation si quelqu'un pense que c'est important d'avoir. Si vous pensez qu'il est important pour nous d'envisager spécifiquement une meilleure pratique autour de « couleur » par rapport à « couleur » maintenant, discutons-en et écoutons ce que les gens en pensent.

Je pense que nous pouvons avoir une conversation pour savoir si nous voulons une meilleure pratique autour des notes finales sans avoir toutes les autres conversations possibles.

@ jnm2 Je pense que c'est assez myope. « Meilleures pratiques » uniquement pour les notes finales ?

je demande à nouveau. Existe-t-il des « meilleures pratiques » équivalentes pour les pages de documentation ? Sinon, je penserais certainement que ce serait une priorité beaucoup plus élevée si la cohérence est ce qui est recherché ici.

Par exemple, j'ai travaillé pour une entreprise où tous les commentaires XML étaient en minuscules. Pas de bouchons en début de ligne. Peut-être devons-nous examiner les problèmes de début et de fin ?

Microsoft fait ces recommandations : https://docs.microsoft.com/en-us/dotnet/csharp/codedoc .

Spécifiquement:

Documenting code is recommended for many reasons. What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your C# code.

-     For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all.
-     Private members can also be documented using XML comments. However, this exposes the inner (potentially confidential) workings of your library.
-     At a bare minimum, types and their members should have a <summary> tag because its content is needed for IntelliSense.
-     Documentation text should be written using complete sentences ending with full stops.
-     Partial classes are fully supported, and documentation information will be concatenated into a single entry for that type.
-     The compiler verifies the syntax of the <exception>, <include>, <param>, <see>, <seealso> and <typeparam> tags.
-     The compiler validates the parameters that contain file paths and references to other parts of the code.
- 

Je suis heureux d'accepter de les recommander comme meilleures pratiques pour la documentation XML NUnit, et je ne passe plus de temps sur ce problème.

@nunit/framework-team D'accord, voici donc les sept directives dont j'aimerais discuter :
https://gist.github.com/jnm2/3f230c9f6343d60bb542938dc35e7a96

Q1 : Lesquelles de celles-ci aimeriez-vous voir comme les meilleures pratiques affectant le produit NUnit Framework ?

Q2 : En plus de rendre le document de bonnes pratiques détectable, voulons-nous demander des modifications si nous remarquons qu'un PR ne suit pas ces directives ? Si non, voulons-nous améliorer la documentation XML publique plus tard ?

Modifications bienvenues.

Les meilleures pratiques ne devraient JAMAIS affecter un PR, ou son acceptation !

Comme je l'ai indiqué ci-dessus, je préférerais adopter des "meilleures pratiques" largement diffusées et largement utilisées, comme documentées par Microsoft dans le lien ci-dessus.

@jnm2

Paragraphe d'introduction : dites quelle est la portée de ceci. Je l'appliquerais aux assemblys framework et engine.api, qui nécessitent une documentation XML sur toutes les méthodes publiques pour éviter les erreurs du compilateur.

Pour ta première question...

Pratique 1 : Exiger une ponctuation de fin (pas des points) pour toutes les phrases. Pour les non-phrases, n'utilisez pas.

Pratique 2 : Je les utiliserais avec parcimonie. Nous n'avons pas besoin d'une référence à une chaîne ou à un int par exemple.

Pratique 3 : j'ajouterais public. Où vous dites qu'il est OK de supprimer add : sauf dans les assemblys où cela provoque une erreur de compilateur.

Pratique 4 : Sauf là où c'est évident. En particulier, ne pas utiliser sur les propriétés.

Exercice 5 : Oui

Exercice 6 : Oui

Pratique 7 : Soyez économe. Ne répertoriez pas les exceptions qui peuvent être levées par un ou la plupart des appels de méthode. Je n'aime pas votre exemple ici car (1) il répertorie les informations deux fois et (2) il utilise cref pour une exception .NET intégrée que tout le monde connaît déjà. Je ne créerais que nos propres affaires, voire pas du tout.

Pour ta deuxième question...

Voulons-nous demander des modifications ? Eh bien, oui, certains d'entre nous le font de toute façon. Nous devrions tous revoir les choses en fonction de notre jugement. Si nous ne sommes pas d'accord, nous nous battons. Il n'est pas possible de dire à l'avance ce qui semblera clair et compréhensible à chacun d'entre nous lorsque nous le verrons, alors reportons-nous sur chaque cas.

Je veux ajouter que la conformité et la cohérence, au-delà du minimum nécessaire à la clarté, n'ont pour nous aucune valeur particulière. Nos utilisateurs sont des programmeurs formés et peuvent comprendre les choses.

@oznetmaster La directive de Microsoft comporte sept points. Mes commentaires...

1. "Par souci de cohérence..." Ce n'est pas la raison pour laquelle nous documentons. Nous documentons pour que les gens sachent comment utiliser notre logiciel. La deuxième phrase de ce point n'a aucun sens pour moi.

2, 3, 4. Faire sens en tant que lignes directrices.

5, 6, 7. Sont des déclarations sur le compilateur, pas des directives de documentation.

Le simple fait de prendre 2, 3 et 4 fait un guide acceptable pour moi.

Franchement, je ne ressens pas le besoin d'une telle directive, mais puisque @jnm2 le fait et est prêt à y travailler, je pense qu'il devrait se sentir libre de le faire.

Lorsqu'il s'agit de réviser le code, n'importe qui est libre de faire n'importe quelle observation, pour n'importe quelle raison et à tout moment. Cela n'exige pas l'autorité d'un document pour le faire. Puisque nous élaborons et appliquons tous les deux les règles, nous n'avons en fait besoin d'écrire que les choses dont nous pensons avoir besoin d'un rappel à l'avenir.

@CharliePoole Fonctionne pour moi.

Cela me semble bien, en le limitant aux seuls types publics.

La cohérence serait bien, mais c'est une très vieille base de code et nous avons peu de temps qu'il vaut mieux consacrer à la correction des bogues et à l'ajout de fonctionnalités. Cela dit, je pense que nous devrions rechercher une documentation trompeuse et je pense également que nous devrions ajouter des informations supplémentaires telles que <see cref="xxx"/> mesure du possible pour améliorer l'expérience de l'outillage.

Aussi, c'est clairement Colour pas Color 😝

@ChrisMaddock Qu'est- @jnm2 ? Je pense vraiment que nous devrions aller avec les trois que @CharliePoole a indiqués dans la liste Microsoft.

@oznetmaster - Désolé, je n'avais pas réalisé que nous

Je n'ai aucune objection à l'option plus hautement spécifiée @jnm2 proposée. L'extrait Microsoft semble en être un sous-ensemble.

Ce n'est pas quelque chose que j'ai personnellement beaucoup d'intérêt à attaquer - cependant, si @jnm2 veut amener la base de code actuelle à cette norme, ce serait sans aucun doute une amélioration. Cela fait partie d'un projet open source non professionnel à mes yeux, il sera toujours motivé dans une certaine mesure par ce sur quoi l'équipe est intéressée à travailler.

Je suis tout à fait d'accord pour rédiger un document « d'orientation » et y travailler en grande partie - je serais heureux de le suivre dans mes propres relations publiques. Je suis moins enthousiaste à l'idée de renvoyer des contributeurs occasionnels pour des changements stylistiques mineurs - mais je pense que nous en avons déjà parlé, et cela doit être traité au cas par cas.

Moi aussi, je pourrais vivre avec l'un ou l'autre, toujours tempéré par un peu de pragmatisme.

Revue de code WRT, c'est un domaine où j'aimerais voir des changements suggérés ou recommandés, avec une justification donnée qui aide les gens à comprendre plutôt qu'une simple référence à un document. Dans le cas des normes de codage, nous pointons simplement sur le document et disons « Ajoutez simplement les traits de soulignement comme il est indiqué ». Ici, OTOH, nous voulons dire : « Cela aidera les utilisateurs si vous faites cela... »

Certains contributeurs occasionnels seront des développeurs expérimentés avec leurs propres notions bien formées sur la façon dont ceux-ci doivent être écrits. Nous devrions accepter cela quand cela arrive, même jusqu'à leur "couleur" préférée.

J'ai intégré les commentaires dans cette page : https://github.com/nuni/docs/wiki/Best-practices-for-XML-documentation.

@CharliePoole

il utilise cref pour une exception .NET intégrée que tout le monde connaît déjà. Je ne créerais que nos propres affaires, voire pas du tout.

Cela fait une différence frappante chaque fois que l'intellisense ou la documentation est visible. Ce n'est pas beaucoup d'effort et le XML brut n'est pas plus difficile que d'habitude à lire. Je ne le découragerais au moins pas si possible.

Il n'y a pas eu d'autres commentaires, donc je considérerai cela comme terminé pour l'instant.