Quelles sont les meilleures pratiques pour Documenter code C # avec des commentaires XML?

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

  •  01-10-2019
  •  | 
  •  

Question

Je vais dans un nouveau code que je viens d'écrire et d'ajouter ndoc commentaires sytle à mes classes et méthodes. J'espère générer un très bon document de style MSDN pour référence.

En général, quelles sont les bonnes directives lors de la rédaction des commentaires pour une classe et une méthode? Que devraient faire les commentaires ndoc dire? Que devraient-ils pas dire?

Je me trouve regarder ce que les commentaires du framework .NET disent, mais qui vieillit rapidement; si je pouvais avoir quelques bonnes règles pour me guider, je pourrais terminer mes docs beaucoup plus vite.

Était-ce utile?

La solution

Dans les commentaires utilisés pour construire la documentation de l'API, vous devez:

  • Expliquez ce que la méthode ou la propriété ne, pourquoi il existe, et d'expliquer les concepts de domaine qui ne sont pas de soi pour le consommateur moyen de votre code.

  • Liste toutes les conditions préalables à vos paramètres (ne peut pas être nulle, doit être dans une certaine plage, etc.)

  • Liste des postconditions qui pourraient influer sur la façon dont les appelants traitent des valeurs de retour.

  • Liste des exceptions de la méthode peut jeter (et dans quelles circonstances).

  • Si des méthodes similaires existent, expliquer les différences entre eux.

  • attention appel à l'imprévu (comme la modification de l'état global).

  • énumérer les éventuels effets secondaires, s'il y en a.

Autres conseils

Si vous vous retrouvez avec des commentaires qui n'ajoutent aucune valeur, ils sont tout simplement inutiles.

Par exemple 

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

... vous a ajouté absolument aucune valeur et juste ajouté plus de code à maintenir.

Code Trop souvent, est jonché de ces commentaires superflus.

StyleCop fournit des conseils pour le code et le style de commenter. Les suggestions qu'il donne sont conformes au style de la documentation MSDN.

En ce qui concerne le contenu du commentaire, il doit donner à l'utilisateur de votre code assez d'informations sur ce type de comportement à attendre. Il devrait également répondre à des questions potentielles que l'utilisateur pourrait avoir. Donc, essayez d'utiliser votre code comme quelqu'un qui ne sait rien sur le code, ou mieux encore, demandez à quelqu'un d'autre de le faire.

Pour les propriétés, votre commentaire doit indiquer si la propriété est en lecture seule, écriture seule ou en lecture écriture. Si vous regardez tous les documents officiels de MS, commentaires doc immobilier commencent toujours par « Gets ... », « Obtient ou définit ... » et (très rarement, éviter d'écriture seulement des propriétés en général) « Sets » ...

Ne pas oublier ce qui est un XML valide. Par exemple: 

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(Erreur: XML non valide).

J'écris le

commentaire à inclure les informations que je voudrais savoir si j'étais celui d'appeler cette fonction (ou consolidait cette classe).

J'écris les commentaire à inclure des informations Je voudrais savoir si j'ai été chargé avec le débogage ou l'amélioration de cette fonction ou de classe. Remarque: cela ne remplace pas le besoin de bons commentaires inline. Mais parfois, un aperçu général du fonctionnement interne de la fonction / classe sont très utiles.

Comme indiqué sur le MSDN , vous utilisez la documentation XML commentaires pour générer la documentation automatiquement, donc il décideurs de sens que si vous écrivez une API et ne veulent pas travailler deux fois à la fois le code et la documentation, avec l'avantage supplémentaire de les maintenir synchronisés - chaque fois que vous modifiez le code, vous modifiez les commentaires appropriés et régénèrent les docs.

Compile avec /doc et le compilateur recherchera toutes les balises XML dans le code source et créer un fichier de documentation XML, puis utilisez un outil tel que Sandcastle pour générer les documents complets.

Une chose au sujet des commentaires est les ACTUALISATION. Trop de gens modifient une fonction alors ne change pas le commentaire pour refléter le changement.

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