Dans notre société, nous écrivons des commentaires XML excessifs. Une méthode typique doit être documentée comme ceci:
/// <summary> /// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>. /// </summary> /// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param> /// <returns> /// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>. /// </returns> bool Contains(ISchedule schedule); /// <summary> /// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/> /// from this <see cref="IScheduler"/>. /// </summary> /// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param> /// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception> /// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception> void Remove(ISchedule schedule);
5 Réponses :
Le point de tous ceux-ci est que, lorsque quelque chose comme Sandcastle est utilisé pour générer des documents HTML ou CHM pour la bibliothèque, ces documents ont une navigation hyperliété entre les objets. Donc, la question est alors, lorsque vous utilisez MSDN, vous trouvez-vous utile de pouvoir cliquer sur un nom de classe A. Donnez-la à l'aide de cette classe ou d'être acceptable de la copier et de la collecter dans le champ de recherche?
Oui, il gonfle le code (bien que des commentaires puissent être effondrés), mais si vous expédiez réellement la documentation à d'autres personnes, elle est assez chère utile.
Il est également très utile lors de l'utilisation de la fonctionnalité Resharper "Documentation rapide" (Ctrl-Q dans mes mappages clés).
Il y a une raison particulière à ces sortes de commentaires: ils peuvent être utilisés pour générer de la documentation ou ajouter des informations supplémentaires à l'autocomplete. Je conviens qu'ils sont trop verbeux et difficiles à lire pour la plupart des situations, mais ils sont bons à ajouter à une interface que vous allez exposer à l'extérieur.
Je recommanderais d'utiliser un éditeur qui vous permet de transformer les commentaires sur et éteindre.
Certaines langues vous permettent de stocker des commentaires sous forme de métadonnées sur des variables et des fonctions, ce qui constitue une belle alternative.
Personnellement, je pense que ce que vous avez est un peu à la mer.
Le but des références "voir" consiste à fournir une bonne liaison entre des sujets dans la documentation d'aide générée après analyse. P>
dans votre cas, vos bibliothèques spécifiques à votre entreprise font référence à des éléments de langue, à savoir: p>
<see langword="true"/>
Ça a l'air intéressant. Il est logique de dire que le consommateur de ma bibliothèque devrait au moins maintenant les jetons de langue intégrés. Bon point.
Ouais - quand je vois des documents qui liennent partout à la BCL partout, cela se présente comme "prêchée" pour moi. Cela suppose simplement que votre utilisateur ne comprend pas ce qu'ils font.
Oui, c'est pourquoi il est plus préférable d'utiliser "voir" les références.
Cette dernière phrase est incroyable.
Comme CTACKE dit, il est très utile de lierlier. Cependant, si vous n'êtes pas réellement expédié la documentation, tout ce que le marquage rend la documentation pratiquement impossible à lire. Dans ce cas, la documentation concerne le développeur (EDIT: interne), et s'il ne peut pas le lire, vous perdez votre temps.
En règle générale, j'ai tendance à faire référence à la première référence à un type ou à un membre, et laissez le reste non associé. Il laisse les commentaires assez propres et fournit toujours un lien significatif.
Lorsque vous travaillez avec Visual Studio, vous pouvez utiliser le plug-in cr_documentor (c'est gratuit, vous pouvez l'obtenir ICI ) pour WYSIWYG-Lecture / rédaction de vos commentaires. Il ressemble à une aide générée de Sandcastle ou de NDOC, mais est rendu à la volée. C'est vraiment utile et vous n'avez pas à vous soucier des commentaires bruts XML.