Règles/directives pour la documentation du code C# ?

Question

Je suis un développeur relativement nouveau et on m'a confié la tâche de documenter le code écrit par un développeur C# avancé. Mon patron m'a demandé de le parcourir et de le documenter afin qu'il soit plus facile de le modifier et de le mettre à jour si nécessaire.

Ma question est la suivante : existe-t-il un type standard de structure de documentation/commentaire que je devrais suivre ? Mon patron m'a donné l'impression que tout le monde savait exactement comment documenter le code selon une certaine norme afin que tout le monde puisse le comprendre.

Je suis également curieux de savoir si quelqu'un a une bonne méthode pour déterminer l'incertitude d'un code ou d'une fonction inconnus. Toute aide serait grandement appréciée.

Answer 1

La norme semble être Doc XML (Article de MSDN Technet aquí ).

Vous pouvez utiliser /// au début de chaque ligne de commentaires de la documentation. Il existe des éléments de style XML standard pour documenter votre code ; chacun d'entre eux doit suivre la norme <element>Content</element> usage. Voici quelques-uns de ces éléments :

<c>               Used to differentiate code font from normal text 
                    <c>class Foo</c>
<code>
<example>
<exception>
<para>            Used to control formatting of documentation output. 
                    <para>The <c>Foo</c> class...</para>
<param>
<paramref>        Used to refer to a previously described <param>  
                    If <paramref name="myFoo" /> is <c>null</c> the method will...
<remarks>
<returns>
<see>             Creates a cross-ref to another topic. 
                     The <see cref="System.String" /><paramref name="someString"/>
                     represents...

<summary>         A description (summary) of the code you're documenting.

Answer 2

On dirait que vous avez vraiment fini par avoir la courte paille.

Malheureusement, je pense que vous êtes tombés sur l'un des sujets les plus controversés du développement logiciel en général. Les commentaires peuvent être considérés comme extrêmement utiles lorsqu'ils sont nécessaires, et inutiles lorsqu'ils sont mal utilisés. Vous devrez être prudent et décider avec soin de ce qui va où.

En ce qui concerne la pratique des commentaires, c'est généralement l'entreprise ou le développeur qui s'en charge. Quelques règles communes que j'aime utiliser sont :

• Commenter la logique qui n'est pas claire (et envisager une refactorisation)
• Seulement les méthodes / propriétés Xml-Doc qui pourraient être remises en question (ou, si vous avez besoin de donner un aperçu plus détaillé)
• Si vos commentaires dépassent la longueur de la méthode ou de la classe qui les contient, vous devriez peut-être réfléchir à la verbosité des commentaires, voire envisager une refonte.
• Essayez d'imaginer un nouveau développeur tombant sur ce code. Quelles questions poserait-il ?

Il semble que votre patron fasse référence au commentaire de la logique (très probablement pour que vous puissiez commencer à la comprendre) et à l'utilisation des commentaires xml-doc.

Si vous n'avez jamais utilisé les commentaires xml-doc, consultez le site ce lien qui devrait vous donner quelques indications sur l'utilisation et les endroits appropriés.

Si votre charge de travail semble un peu lourde (c'est-à-dire beaucoup de code à commenter), j'ai de bonnes nouvelles pour vous - il existe un excellent plugin pour Visual Studio qui peut vous aider pour les commentaires xml-doc. GhostDoc peut faciliter le commentaire des méthodes/classes dans les documents xml (mais n'oubliez pas de changer le texte par défaut qu'il insère dans ces documents !)

N'oubliez pas que vous pouvez vérifier auprès de votre patron quelles sont les parties du code qu'il souhaite voir documentées avant de vous lancer dans la création d'un document fantôme.

Answer 3

C'est un peu inquiétant que le programmeur original n'ait pas pris la peine de faire l'une des parties les plus importantes de son travail. Cependant, il y a beaucoup de "bons" programmeurs terribles, donc ce n'est pas si inhabituel.

Cependant, le fait de vous faire documenter le code est également un très bon mécanisme de formation - vous devez lire et comprendre le code avant de pouvoir écrire ce qu'il fait, et en plus d'acquérir des connaissances sur les systèmes, vous allez sans aucun doute apprendre quelques trucs et astuces à partir des bonnes (et mauvaises !) choses que l'autre programmeur a faites.

Pour vous aider à rédiger votre documentation de manière rapide et cohérente, vous pouvez essayer mon module complémentaire pour Visual Studio, Documentation sur AtomineerUtils Pro . Cela vous permettra d'éviter le travail fastidieux de création et de mise à jour des commentaires, de vous assurer que les commentaires sont complets et en phase avec le code, et de vous concentrer sur le code lui-même.

Quant à savoir comment le code fonctionne...

Espérons que les noms des classes, des méthodes, des paramètres et des variables seront descriptifs. Cela devrait vous donner un assez bon point de départ. Vous pouvez ensuite prendre une méthode ou une classe à la fois et déterminer si vous pensez que le code qu'elle contient fournit ce que vous pensez que le nom implique. S'il existe des tests unitaires, ils vous donneront une bonne indication de ce que le programmeur attendait du code (ou de sa gestion). Quoi qu'il en soit, essayez d'écrire quelques tests unitaires (ou plus) pour le code, car en réfléchissant aux cas particuliers qui pourraient casser le code et en déterminant pourquoi le code échoue à certains de vos tests, vous aurez une bonne compréhension de ce qu'il fait et de comment il le fait. Vous pourrez ensuite ajouter à la documentation de base que vous avez rédigée les détails les plus utiles (ce paramètre peut-il être nul ? quelle plage de valeurs est légale ? Quelle sera la valeur de retour si vous passez une chaîne vide ? etc).

Cela peut être décourageant, mais si vous commencez par les petites classes et méthodes (par exemple, la propriété Name qui ne renvoie qu'une chaîne de caractères), vous vous familiariserez avec le code environnant et serez en mesure de passer progressivement aux classes et méthodes plus complexes.

Une fois que vous avez rédigé la documentation de base du code pour les classes, vous devriez être en mesure de rédiger une documentation de synthèse externe qui décrit le fonctionnement du système dans son ensemble. Vous serez alors prêt à travailler sur cette partie de la base de code, car vous comprendrez comment tout s'imbrique.

Je recommanderais d'utiliser la documentation XML (voir les autres réponses) car elle est immédiatement récupérée par Visual Studio et utilisée pour l'aide intellisense. Ainsi, toute personne écrivant du code qui appelle vos classes recevra de l'aide dans des infobulles au fur et à mesure qu'elle tape le code. Il s'agit d'un avantage majeur lorsqu'on travaille avec une équipe ou une base de code importante, mais de nombreuses entreprises/programmeurs ne réalisent pas ce qu'ils ont manqué, en tapant leurs pierres (non documentées) ensemble dans les âges sombres :-)

Answer 4

Je soupçonne votre patron de faire référence aux commentaires suivants de la documentation XML.

Commentaires sur la documentation XML (Guide de programmation C#)

Answer 5

Il peut être intéressant de demander à votre patron s'il a des exemples de code déjà documenté, afin que vous puissiez vous rendre compte par vous-même de ce qu'il recherche.

Mark Needham a écrit quelques articles de blog sur la lecture/documentation du code (voir Archives pour la catégorie 'Code de lecture'. .

Je me souviens avoir lu Code de lecture : Rhino Mocks Il y a quelque temps, j'ai lu un article qui parlait de la schématisation du code pour vous aider à savoir où vous en êtes et à " cartographier " ce qui se passe.

J'espère que cela vous aidera - bonne chance !