XML Commentant des conseils pour la programmation C # [fermé]

Question

Bonjour, après-midi, le soir ou la nuit (en fonction de votre fuseau horaire).

Ceci est juste une question générale sur XML C # au sein des commentaires. Je ne l'ai jamais été très grand en commentant mes programmes, je l'ai toujours été plus d'une variable verbose / propriété / méthode Namer et de laisser le code parle pour lui-même. Je n'écrire des commentaires si je codantes quelque chose qui est assez déroutant, mais pour la plupart, je ne vous écris pas beaucoup de commentaires.

Je faisais quelques lectures sur les commentaires XML dans .NET, Sandcastle, et le constructeur de fichiers d'aide CodePlex et il m'a pris sur le chemin de vouloir documenter mon code et générer de belles, la documentation utile pour ceux qui doivent creuser dans mon code quand je ne serai plus là.

Ma question concerne les normes et conventions. Yat-il un guide XML « bon » de commenter? Si vous commenter toutes les variables et les biens? Chaque méthode? Je cherche juste fondamentalement des conseils sur la façon d'écrire de bons commentaires qui seront compilés par Sandcastle dans une bonne documentation pour que les autres programmeurs ne maudissez pas mon nom quand ils finissent par avoir à travailler sur mon code.

Merci d'avance pour vos conseils et suggestions, Scott Vercuski

Answer 1

Personnellement, nous nous assurons que toutes les méthodes publiques et protégées a des commentaires XML. Il sera également vous fournir IntelliSense, et pas seulement la documentation d'aide utilisateur final. Dans le passé, nous avons également inclus sur les déclarations privées scope, mais ne se sentent pas 100% nécessaire, aussi longtemps que les méthodes sont courtes et points.

Ne pas oublier qu'il existe des outils pour vous faire XML tâches commentent plus facile:

• GhostDoc -. Héritage Commentaire et templating add-in
• Sandcastle Aide Générateur de fichiers - Permet de modifier les projets Sandcastle via une interface graphique, peut être exécuté à partir d'une ligne de commande (pour l'automatisation de construction), et peut modifier GAML des rubriques d'aide non dérivés du code. (La 1.8.0.0 version alpha est très stable et très améliorée. Avoir été utilisé pendant environ un mois, plus 1.7.0.0)

Answer 2

Les commentaires sont très souvent dépassées. Cela a toujours été un problème. Ma règle empirique:. Plus vous devez travailler pour mettre à jour un commentaire, plus ce commentaire sera obsolète

Commentaires XML sont parfaits pour le développement de l'API. Ils fonctionne assez bien avec Intellisens et ils peuvent vous faire générer un document d'aide HTML en un rien de temps.

Mais ce n'est pas libre: les maintenir sera difficile (regarder tout exemple non trivial, vous comprendrez ce que je veux dire), donc ils ont tendance à être dépassée très vite. En conséquence, d'examiner les commentaires XML devraient être ajoutés à votre revue de code comme une vérification obligatoire et ce contrôle doit être effectué chaque fois qu'un fichier est mis à jour.

Eh bien, car il est coûteux à entretenir, car beaucoup de symboles non privés (dans le développement non-API) ne sont utilisés que par 1 ou 2 classes, et je n'appliquer car ces symboles sont souvent explicites, un règle disant que chaque symbole non-privé devrait être XML commenté. Ce serait surpuissant et conterproductive . Ce que vous obtiendrez est ce que je voyais à beaucoup d'endroits: près de commentaires XML vides ne rien ajouter au nom du symbole. Et le code qui est juste un peu moins lisible ...

Je pense que le très, très importante ligne de guide sur les commentaires dans le code normal (non-API) ne devrait pas être sur comment ils doivent être écrits mais de Qu'est-ce qu'ils doivent contenir . Beaucoup de développeurs ne savent toujours pas ce pour écrire. Une description de ce qui devrait être commenté, avec des exemples, ferait mieux pour votre code que juste une plaine: «N'utiliser les commentaires XML sur tous les non-privé symbole ».

Answer 3

classes de documents publics et les membres du public / Protected de ces classes.

Je ne documentent pas membres privés ou internes ou des classes internes. D'où les variables (je pense que vous voulez dire des champs) parce qu'ils sont privés.

L'objectif est de créer de la documentation pour un développeur qui n'a pas accès à code source.

S'efforcer de placer quelques exemples où l'utilisation est pas évident.

Answer 4

Je remarque très rarement sur les variables de la méthode, et les champs tout aussi rarement (car ils sont généralement couverts par une propriété, ou tout simplement n'existe pas en cas d'utilisation des propriétés implémentées automatiquement).

En général, j'essaie d'ajouter des commentaires significatifs à tous les membres du public / protégés, ce qui est à portée de main, car si vous activez les commentaires xml lors de la construction, vous obtenez des avertissements automatiques pour commentaires manquants. En fonction de la complexité, je ne pourrais pas remplir tous les détails - à savoir si elle est 100% évident que tous les paramètres a à faire (il n'y a pas de logique particulière, et il n'y a que 1 façon logique d'interpréter les variables), alors je peut paresseux et ne pas ajouter des commentaires sur les paramètres.

Mais j'essaie certainement de décrire les méthodes, types, propriétés, etc. représentent / faire.

Answer 5

Nous documentons les méthodes publiques / propriétés / etc sur nos bibliothèques. Dans le cadre du processus de construction que nous utilisons NDoc pour créer une référence Web MSDN-like. Il a été très utile pour une référence rapide et recherche.

Il est également grand pour IntelliSense, en particulier avec les nouveaux membres de l'équipe ou, comme vous l'avez dit, lorsque l'auteur original a disparu.

Je suis d'accord que le code, en général, doit être explicite. Le documention XML, pour moi, est plus sur la référence et recherche lorsque vous n'avez pas la source ouverte.

Answer 6

Personnellement, mon avis est d'éviter de commenter. Commentant est dangereux. Parce que dans l'industrie, nous le code toujours à jour (parce que les affaires et les besoins changent toujours), mais rarement varions nous mettons à jour nos commentaires. Cela peut désorienter les programmeurs.