Pourquoi les /// blocs de commentaires sont-ils importants?


49

Quelqu'un a dit une fois que nous devrions préfixer toutes nos méthodes avec les /// <summary>blocs de commentaires (C #) mais n’a pas expliqué pourquoi.

J'ai commencé à les utiliser et j'ai constaté qu'ils m'ennuyaient un peu, alors j'ai cessé de les utiliser, sauf pour les bibliothèques et les méthodes statiques. Ils sont encombrants et j'oublie toujours de les mettre à jour.

Existe-t-il une bonne raison d'utiliser des /// <summary>blocs de commentaires dans votre code?

J'utilise normalement des //commentaires tout le temps, ce sont juste les /// <summary>blocs sur lesquels je m'interrogeais.


1
Je ne savais pas si ces commentaires étaient des préférences personnelles ou des normes recommandées
Rachel le

1
Je pense aussi.
Ryan Hayes

30
Je pense que c'est exactement le genre de question qui se pose ici. Il y a de fortes chances pour que cela soit fermé sur stackoverflow comme étant subjectif.
Paddyslacker

Utilisez des blocs <summary> si vous souhaitez générer de la documentation. Cela aurait du sens si vous créez une API que d'autres pourront utiliser. Faire cela pour chaque méthode est excessif et diminue votre flexibilité.
Macneil

Réponses:


91

Utilisez-les autant que possible.

Oui, ce sont des commentaires spéciaux qui deviennent la documentation de la méthode. Le contenu des <summary>balises de paramètre, etc. générées apparaît en intellisense lorsque vous ou une autre personne s'apprête à appeler votre méthode. Ils peuvent essentiellement voir toute la documentation de votre méthode ou de votre classe sans avoir à consulter le fichier lui-même pour savoir ce qu’il fait (ou essayer de lire simplement la signature de la méthode et espérer que tout ira au mieux).


22
+1 Absolument les utiliser. Vous seriez surpris de voir à quel point il est utile de les obtenir si vous réutilisez vos composants et que vous disposez de toute cette documentation de qualité disponible dans intellisense.
Walter

4
De même, si vous utilisez Visual Studio et que vous commencez une ligne par /// juste avant une déclaration de classe, de méthode ou de champ, VS générera la structure de documentation XML pour vous. Il vous suffit de la compléter. Je conviens que cela prend beaucoup d'espace de votre écran, mais c'est un compromis digne je dirais. De plus, F # supporte mieux le contenu (par exemple, vous n'avez pas besoin d'utiliser <summary> et </ summary> car ils sont "supposés").
ShdNx

7
Parce que cette réponse est déjà le meilleur choix, je vais juste ajouter mon commentaire: Quand j'ai découvert que le résumé était utilisé pour intellisense, et que mes projets ont pris de la taille, je suis très heureux d'avoir trouvé cette fonctionnalité. Se souvenir de mes méthodes et de mes classes devenait un énorme défi, et documenter du code via ce mécanisme simplifiait grandement les choses, me permettant de me concentrer sur le nouveau code et la possibilité de réutilisation au lieu d'essayer de me souvenir de ce qui avait été fait il y a des mois.
JYelton

3
Juste une chose à ajouter, ces commentaires ne sont pas compilés dans la dll, vous devez livrer le fichier xml associé avec votre dll.
Benjol

Ils sont utiles, mais ils rendent la classe actuelle très illisible. J'aimerais qu'il y ait un autre moyen de ne pas encombrer le code.
Jeroen van Langen

17

Oui, utilisez-les absolument pour tout ce que vous souhaitez conserver ou partager.

Utilisez-les également avec Sandcastle et Sandcastle Help File Builder , qui prennent la sortie XML et la transforment en une magnifique documentation de style MSDN.

Au dernier endroit où j'ai travaillé, nous avons reconstruit la documentation tous les soirs et l'avons hébergée en tant que page d'accueil interne. Les initiales de la compagnie étaient MF, donc c'était MFDN;)

Normalement, je produis simplement un fichier .chm, qui est facilement partagé.

Vous seriez surpris de voir à quel point vous êtes accro à tout documenter une fois que vous commencez à le voir au format MSDN!


1
Le lien vers le blog semble être mort (le dernier message il y a 5 ans avec du HTML cassé sur toute la page) et l'emplacement du projet a été modifié. Avez-vous un lien mis à jour pour Sandcastle?

12

Si votre norme de codage exige que vous utilisiez de tels commentaires (et qu'une norme de codage pour une API ou un framework puisse l'exiger), vous n'avez alors pas le choix, vous devez utiliser ces commentaires.

Sinon, envisagez sérieusement de ne pas utiliser de tels commentaires. Vous pouvez les éviter dans la plupart des cas en modifiant votre code comme suit:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

à

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

à

    public bool IsAuthorizedToAccessResource( User user ) {

    }

11
Bien que je convienne que le code devrait s'auto-documenter aussi souvent que possible, je suggère d'utiliser ces types de commentaires chaque fois que possible (et plus souvent que // commentaires génériques). Les /// XML commentaires sont conçus pour fonctionner avec IntelliSense, ce qui peut faciliter le développement des mois à venir lorsque vous essayez d'implémenter une bibliothèque que vous avez construite et ne vous rappelez plus très bien comment cela fonctionne.
Matt DiTrolio

2
Et je pense que non seulement du point de vue d’Intellisense, mais aussi du point de vue de la génération automatique de documentation, les commentaires XML sont utiles. Mais comme pour tous les commentaires, cela n’a de sens que si les commentaires eux-mêmes sont utiles et s’ajoutent au code auto-documenté.
Vaibhav

5
Je conviens que lorsque vous écrivez des classes publiques d'une API ou d'un framework, la norme de codage doit exiger que vous ajoutiez des commentaires dans le code de sorte que IntelliSense et les outils de documentation puissent s'y brancher. Mais ce n'est pas tout le code. Outre cette préoccupation, l'approche que je préconise est la suivante: lorsque vous essayez de rendre votre code plus propre et plus clair, concentrez-vous sur le code lui-même, et non sur le commentaire qui le décrit.
azheglov

3
@JYelton: votre commentaire déforme ma réponse. J'impliquais des noms plus descriptifs, mais pas nécessairement beaucoup plus verbeux, certainement pas un identifiant à 60 caractères pour une fonction publique fréquemment appelée. En outre, vous avez ce qui semble être une fonction hautement spécialisée, mais il faut un type de données très général (XmlDocument) - c'est une odeur de code. Ensuite, votre identifiant de 60 caractères décrit le "comment" et non le "quoi" d'une méthode publique. C'est une autre odeur. Le message principal est le suivant: pensez d'abord au code, pas au commentaire.
azheglov

2
@JYelton Le problème avec le nom de votre méthode n'est pas qu'il est descriptif, mais décrit plutôt au moins 2 opérations distinctes et doit donc être refactorisé en au moins 2 méthodes indépendantes.
Neal

4

Votre nom de classe, méthode et propriété devrait être évident, alors si vous en avez besoin, c'est probablement une odeur.

Cependant, je recommanderais de les utiliser sur toutes les classes, méthodes et propriétés publiques dans une API, une bibliothèque, etc. pour les écrire.

Mais de toute façon, vous la coupez, la maintenez ou la supprimez.


11
Nommer est une chose, mais lister les contraintes sur les paramètres ou les exceptions potentiellement levées est toujours utile.
Adam Lear

Oui, je vous concède que vous avez un point, mais la plupart du temps, les contraintes de paramètres sont évidentes, n'est-ce pas?
John MacIntyre le

Pas sûr que je sois d'accord avec John. Avec cette logique, aucune des méthodes du cadre .net ne doit obtenir d'aide de Intellisense.
Vaibhav

1
@vaibhav - J'ai dit: "Je recommanderais de les utiliser pour toutes les classes, méthodes et propriétés publiques dans une API, une bibliothèque, etc." ... qui couvriraient ce dont vous parlez, n'est-ce pas?
John MacIntyre le

1
@ John - étrange, j'aurais juré avoir lu autre chose lorsque j'ai écrit ce commentaire. Parce que votre deuxième paragraphe est exactement ce que j'ai dit ailleurs dans ce fil. Donc, je dois avoir des pierres dans la tête pour écrire ce commentaire. Oui, je suis d'accord avec ça.
Vaibhav

2

Si vous vous rendez compte que vous devez sans cesse revenir en arrière et modifier vos commentaires pour les adapter au nouveau code, vous risquez de les avoir mal interprétés. L'élément summary doit contenir exactement cela - un résumé - le quoi et le pourquoi de la chose que vous résumez.

Décrire comment quelque chose fonctionne dans les commentaires est une violation de DRY. Si votre code n'est pas suffisamment descriptif, vous devriez peut-être revenir en arrière et refactoriser.


1

Oui, je les ai créés. [lors de la construction de nouveaux systèmes à partir de zéro]

Non, je n'ai jamais bénéficié d'eux. [lorsque vous travaillez sur des systèmes existants nécessitant une maintenance]

J'ai constaté que les commentaires "Résumé" finissent par ne plus être synchronisés avec le code. Et une fois que j'ai remarqué quelques commentaires qui se comportent mal, j'ai tendance à perdre confiance en tous les commentaires sur ce projet - vous ne savez jamais à qui faire confiance.


Les commentaires obsolètes peuvent être considérés comme une odeur de code, encore plus au niveau du résumé. Si d'autres développeurs changent de fonction et ne mettent pas à jour le résumé de ce qu'ils font, on pourrait alors affirmer qu'ils ne documentent pas correctement leur travail.
rjzii

1

Oublier de faire quelque chose n'en fait pas une mauvaise idée. Oublier de mettre à jour une documentation est. Je les ai trouvées très utiles dans ma programmation et les personnes qui héritent de mon code sont reconnaissantes de les avoir.

C'est l'un des moyens les plus visibles de documenter votre code.

Il est difficile de trouver le code source pour lire la documentation en ligne ou de déterrer un document qui décrit le code. Si vous pouvez faire apparaître quelque chose d'utile par l'intelligence, les gens vous aimeront.


1

" Il doit être très utilisé, comme moi;) "

Je jouais avec des commentaires (///). Pour un cours, vous pouvez simplement faire un commentaire comme celui-ci.

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Mais, pour une méthode, vous pouvez en ajouter davantage avec une description des paramètres et des types de retour.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Vous pouvez utiliser un raccourci pour créer ce commentaire (///+Tab).


0

les utiliser sauf pour les bibliothèques

C'est le moment où ils sont utiles. Avec la génération de documentation XML activée et une référence à l’assemblage, sans son projet, affichera plus de détails dans intellisense.

Mais pour les internes du projet actuel, ils ne font que gêner.


0

Je les utilise, mais comme d'autres personnes l'ont dit, pas universellement. Pour les petites méthodes, elles peuvent facilement être plus volumineuses que le code qu'elles expliquent. Ils sont particulièrement utiles pour générer de la documentation pouvant être transmise aux nouveaux utilisateurs du système afin qu’ils puissent se référer à quelque chose tout en l’apprenant. Même si, en tant que programmeurs, nous pouvons généralement trouver le code qui convient, il est bon que les commentaires nous guident et agissent comme une béquille. S'il doit être écrit quelque part, le code est l'endroit où il est le plus susceptible de rester à jour (plus probable qu'un document Word flottant).


0

J'utilise l'équivalent en VB (car ils ne me laisseront pas utiliser C # - apparemment, c'est trop difficile ... sans commentaire.) Je les trouve très pratiques. La plupart du temps, j'attends que la procédure ou la fonction soit à peu près terminée avant de les insérer, ne serait-ce que pour éviter de devoir modifier les commentaires ou les faire "désynchronisés".

Je n'écris pas nécessairement un roman - juste la base, la description du paramètre et quelques remarques (généralement quand il se passe quelque chose "d’extraordinaire" là-dedans - solution de contournement ou autre merde que je préférerais ne pas avoir là-dedans pas de choix "pour l'instant".) (Ouais, je sais, que "pour l'instant" peut durer des années.)

Je suis gravement irrité par le code non commenté. Un consultant a écrit la version initiale de l’un de nos composants sans rien commenter et son choix de noms laisse à désirer ici et là. Il est parti depuis un an et nous sommes toujours en train de trier ses affaires (en plus de travailler sur nos propres affaires).

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.