Comment documenter votre code .NET avec des commentaires XML

Dans tout environnement professionnel, documenter correctement votre code avec des commentaires est nécessaire pour une lisibilité à long terme. Pour le code .NET, Microsoft fournit un système de commentaires XML qui fournissent une prise en charge améliorée de l'EDI.

Que sont les commentaires XML?

Essentiellement, les commentaires XML sont un type spécial de commentaire indiqué par une triple barre oblique (///) et des balises XML pour donner une structure au commentaire. Par exemple, un simple commentaire de résumé ressemblerait à ce qui suit:

Le fait est que lorsque vous utilisez cette méthode ailleurs dans votre code, Visual Studio peut consulter le XML et ajouter des informations directement dans la fenêtre contextuelle Intellisense. Ce système fonctionne pour tous les types de types et peut même être utilisé pour documenter les valeurs de retour et les paramètres individuels. Et, lorsque vous distribuez l'assembly, vous pouvez distribuer le fichier XML avec lui pour activer ces mêmes fonctionnalités pour toute personne utilisant votre bibliothèque de classes. Cela permet également une utilisation facile des générateurs de documentation statiques tels que DocFX et Sandcastle.

Étonnamment, cette fonctionnalité est principalement une chose .NET. Rien ne vous empêche d'utiliser la pratique avec d'autres langues, mais c'est quelque chose que Microsoft prend bien en charge pour leurs langues et éditeurs, et les autres langues ne sont généralement pas prises en charge correctement. Nous aimerions voir la prise en charge de cette fonctionnalité étendue à d’autres langues et éditeurs, car elle est universellement utile.

C’est très simple à utiliser. Appuyez simplement sur la touche barre oblique trois fois (///) au-dessus d'une méthode, d'une classe ou d'un autre type, et Visual Studio insérera un modèle que vous pourrez taper. Cela vous évite d'avoir à le taper manuellement, ce qui signifie qu'il n'y a vraiment aucune raison de ne pas les utiliser par rapport aux commentaires traditionnels à double barre oblique .

Si votre méthode a un type de retour ou des paramètres, Visual Studio générera également des champs pour ceux-ci. Vous verrez vos commentaires lorsque vous utiliserez la méthode:

La norme prend en charge de nombreux types de balises:

• s'affiche dans Intellisense chaque fois que vous utilisez la méthode.
• est comme un résumé, mais ne s'affiche pas dans Intellisense (utile pour rédiger une documentation étendue).
• documente le type de retour.
• permet aux développeurs de savoir quelles exceptions la méthode peut générer.
• est comme les retours mais pour les propriétés de classe.
• montre un exemple de code pour la documentation (utilisez-le avec ).
• et générer des liens cliquables vers d'autres méthodes, généralement utilisées pour documenter les surcharges.
• permet d'utiliser des listes pour ordonner les éléments.