Bien Commenter Et Documenter Son Code en C

5/16/2018 Bien Commenter Et Documenter Son Code en C - slidepdf.com

http://slidepdf.com/reader/full/bien-commenter-et-documenter-son-code-en-c 1/39

Bien commenter et documenter

son code en C#Date de publication : 03 octobre 2005 , Date de mise à jour : 03 octobre 2005

Par Lainé Vincent (autres articles)

Ce tutoriel à pour but de donner quelques règles simples afin de bien commenter etdocumenter son code en C#

I. Introduction II. Commenter le code II-A. Que faut-il commenter dans le code ?

II-B. Comment le commenter ? II-C. Conclusion sur les commentaires III. Documenter le code III-A. Documenter oui, mais comment ?

III-B. Les tags de documentations

III-B-1. Le tag "summary"

III-B-2. Le tag "param"

III-B-3. Le tag "returns"

III-B-4. Le tag "value"

III-B-5. Le tag "paramref"

III-B-6. Le tag "c"

III-B-7. Le tag "remarks"

III-B-8. Le tag "exception"

III-B-9. Le tag "example"

III-B-10. Le tag "code"

III-B-11. Le tag "see"

III-B-12. Le tag "seealso"

III-B-13. Le cas des listes III-C. Comment générer la documentation ?

III-C-1. Génération de la documentation avec NDoc IV. Remerciement V. Liens utiles

I. IntroductionCompatible avec :

http://www.developpez.net/forums/profile.php?mode=viewprofile&u=42863


http://vincentlaine.developpez.com/



http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LI


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LII


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LII-A


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LII-B


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LII-C


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIII


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIII-A


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIII-B


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIII-B-1


























http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIII-C


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIII-C-1


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LIV


http://vincentlaine.developpez.com/tuto/dotnet/comdoc/#LV































La lecture de ce tutoriel ne requiert aucune connaissance particulière si ce n'est les bases de

la programmation en C#.Tout au long de ce tutoriel je m'enfforcerai de faire la distinction entre ce qui est admis partous et les règles que j'applique moi même.L'idée de ce tutoriel vient d'un sujet de discussion sur le forum.Je tiens également à préciser que les exemples de code sont volontairement simplistes etparfois un développeur expérimenté ne trouvera pas les commentaires pertinents; toutefoisle tutoriel vise un public débutant.

Tout les mots entre " du tutoriel sont des tags de documentation. Tout les mots en gras

sont des mots clefs du langage et tous les mots en italique sont des arguments des tags

de documentation.

II. Commenter le codeCommenter le code ... Tout le monde en a entendu parler, les développeurs/chefs deprojets/professeurs le disent tout le temps : "Commente ton code STP".Mais voilà, que faut-il commenter ? Comment le commenter ?C'est à ces deux principales questions que je vais essayer de répondre .

II-A. Que faut-il commenter dans le code ?

Assurément, il ne faut pas tout commenter dans un code. C'est d'ailleurs un des problèmesrencontrés assez régulièrement quand l'on travaille en équipe : soit le code n'est pas dutout commenté, soit il l'est trop.Sachez que dans les deux cas le résultat est le même : le code est illisible.Afin d'avoir un code facilement lisible par une tierce personne (ou par soi-même d'ailleurs),il faut donc le commenter de manière intelligente, c'est à dire ni trop ni pas assez et avecprécision.Exemple :

public void Main(string[] args){

//LancementApplication.Run(new MainForm());

}

Ceci est un exemple parfait de ce qu'il ne faut pas faire. Le commentaire est imprécis etinutile. Dans un cas comme ça je préfére laisser au développeur le soin de chercher dans ladocumentation du framework à quoi sert Application.Run et comment l'on s'en sert. De pluscette ligne est une ligne que (normalement) tout développeur .NET a déjà vue au moins une



fois dans sa vie. Le commentaire est donc superflu car aucune information utile n'estapportée ici.

public void Switch(ref int a, ref int b){

a *= b;b = a/b;

a = a/b;}

Ce code n'a rien d'extraordinaire mais il est déjà un peu plus complexe. Bien qu'il ne faillepas longtemps pour le comprendre, il peut être commenté afin de faciliter la lecture. Voilàcomment je l'aurais commenté :

Les mots-clefs ref ne sont pas l'objet du tutoriel, si vous ne savez pas à quoi ils servent,

la documentation du framework vous éclairera dessus.


//Effectue l'échange de a et b

a *= b;b = a/b;a = a/b;

}

Ce commentaire permet de tout de suite comprendre ce que fait le code en dessous. Il estclair, précis et concis.

II-B. Comment le commenter ?Dans ce paragraphe je ferais juste un petit rappel des techniques de commentaires etensuite j'expliquerai comment commenter clairement le code.Les différentes techniques de commentaire en C# sont les suivantes :

// Commentaire sur une ligne, idéal pour une description courte d'uncode pas trop complexe

/*Commentaire sur plusieurs lignes pour une desciption longue.Cela permet d'aérer le commentaire afin de ne pas en faire un gros

pavé illisible.Je pourrais m'étendre encore longtemps comme ça mais vous avez

compris je pense ;-)*/

Ce sont là deux grandes méthodes de commentaire dans un code C#.Revenons plutôt au code précédent afin d'en analyser le commentaire :


//Effectue l'échange de a et ba *= b;b = a/b;



a = a/b;

}

A ce stade, deux choix sont possibles :- Soit le code commenté n'est qu'une partie annexe de l'algorythme et ce type de

commentaire suffit car il n'est pas indispensable de comprendre parfaitement le code endessous pour comprendre le programme.- Soit le code commenté est un "pilier" du programme auquel cas il faut plus le détailler.Partons de l'hypothèse que ce code est un des piliers de votre nouvelle bibliothèque demaths et regardons comment nous pourrions le commenter un peu plus :


//Effectue l'échange de a et ba *= b;

//b vaut maintenant a (b = (ab)/b d'ou b = a)b = a/b;//a vaut maintenant b (a = (ab)/a (car b = a) d'ou a = b)

a = a/b;

}

Comme vous le voyez, les différentes étapes (stades) de l'algorithme sont commentés et justifiés afin d'en faciliter la compréhension

L'exemple étant fictif et simpliste, le commentaire perd de sa pertinence et de sa

justification mais bon il est là à titre d'exemple.

II-C. Conclusion sur les commentaires

Il n'existe pas de règles de commentaires autre que le bon sens. Ces commentairesreflètent la manière dont je travaille et peuvent ne pas vous convenir.C'est d'ailleurs un des problèmes du travail à plusieurs : Un développeur peut trouver qu'uncommentaire est justifié alors qu'un autre ne le pense pas.

III. Documenter le codeAprès avoir vu comment commenter le code afin de le partager avec sescollègues/amis/équipiers, nous allons voir comment le documenter afin qu'une personneexterne (ou interne) au projet puisse utiliser ce que l'on a développé.La documentation est un point essentiel de toute librairie destinée à être utilisée pard'autres développeurs. Imaginez que l'équipe qui a développé .NET n'ait pas du toutdocumenté le code. Il serait impossible de consulter la documentation de telle ou telle



classe afin de savoir comment il faut utiliser une méthode.Impensable de nos jours.C'est pour cela que les tags de documentation sont là. Ils vous permettent de documenter lecode à l'interieur de celui-ci afin que la documentation soit partie intégrante du projet.Ainsi chaque développeur a la responsabilité de la documentation de son code. Et d'ailleursqui d'autre que le développeur qui a écrit cette fonction peut mieux la documenter ?

Dans cette partie nous verrons comment documenter une classe, une fonction, unepropriété et ensuite nous verrons un outil qui permet de générer la documentation auformat HTML et chm (HTML compilé) à partir du fichier .xml généré par le compilateur C#.

III-A. Documenter oui, mais comment ?

Afin de documenter le code il existe un format de commentaire particulier qui indique aucompilateur de traiter les commentaires comme de la documentation.

En fait il en existe plusieurs mais seul le format le plus courant sera traité ici. Pour plus

d'informations voir la documentation du framework.

Ce format est tout simple :

///

il s'agit de trois slash ( / ) à la suite. Dans Visual Studio et SharpDevelop, le fait de mettretrois slash à la suite dans un endroit valide fait apparaitre un menu avec les tags dedocumentation. C# builder 1.0 n'a hélas pas le même comportement.Bien, vous savez donc maintenant informer le compilateur que ce qui va suivre doit être dela documentation.

III-B. Les tags de documentations

Le langage C# définit une vingtaine de tags de documentation afin de gérer toutes lespossibilitées et ainsi d'avoir une documentation claire et standard.

III-B-1. Le tag "summary"Le tag "summary" sert à donner la description complète de l'élément que l'on souhaitedocumenter. Il peut être utilisé sur une classe, une fonction, propriété ou une variable.Ce tag est un des tags de base de la documentation.

/// <summary>/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// </summary>



public class MaClasse{

/// <summary>/// Description de la variable et de son rôle dans le

programme/classe./// </summary>public static int maVariable;

/// <summary>/// Description complète de la fonction. Généralement on donne

le but de la fonction./// </summary>public void UneMethode(){...

}

/// <summary>/// Description complète de la propriété./// Attention il n'est pas nécessaire de préciser si elle est

en lecture seule ou non,/// le fait d'avoir seulement le get permet au générateur de

documentation de marqué la propriété comme étant en lecture seule./// </summary>public int UnePropriete{

get{

...}

}}

Comme vous le constatez la balise "summary" n'est pas difficile à utiliser. Cette balise

devrait être présente sur toutes les classes, méthodes, propriétés, variables marquées"public" d'un programme.

III-B-2. Le tag "param"

Le tag "param" permet de documenter les paramètres d'une fonction ou d'une propriété. Ilprend en complément le nom de la variable. Le type de la variable est automatiquementdéterminé par le générateur de documentation.

/// <summary>

/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// </summary>public class MaClasse{

/// <summary>/// Une méthode qui ne fait rien ;-)/// </summary>/// <param name=a>parametre qui ne sert à rien du



tout.</param>public void UneMethode(int a){

}

}

Cette balise est pratiquement indissociable de la balise "summary" pour les fonctions.

III-B-3. Le tag "returns"

Le tag "returns" permet de documenter la valeur de retour d'une fonction seulement. Sonutilisation est très simple.

/// <summary>/// Description complète de la classe. Généralement on donne la

fonction de cette classe ainsi que ces particularités/// </summary>public class MaClasse{

/// <summary>/// Une méthode qui ne fait rien ;-)/// </summary>/// <param name=a>parametre qui ne sert à rien du

tout.</param>/// <returns>Valeur passée en argument non modifiée car la

fonction ne fait rien .</returns>public int UneMethode(int a){

return a;}

}

III-B-4. Le tag "value"

Le tag "value" permet de décrire la valeur de retour ou d'entrée d'une propriété. Elle joue lemême rôle que la balise "param" pour une fonction.

/// <summary>

/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// </summary>public class MaClasse{

/// <summary>/// Une propriétée./// </summary>/// <value>Renvois toujours 10</value>



public int UnePropriete{

get{

return 10;}

}}

III-B-5. Le tag "paramref"

Le tag "paramref" permet d'indiquer que le mot dans le commentaire est un paramètre de lafonction. Cela permet au générateur de documentation de faire la distinction lors de lagénération.


fonction de cette classe ainsi que ces particularités/// </summary>public class MaClasse{

/// <summary>/// Une méthode qui ne fait rien ;-) avec <paramref name="a"

/>/// </summary>/// <param name=a>parametre qui ne sert à rien du


fonction ne fait rien .</returns>public int UneMethode(int a){

return a;}

}

III-B-6. Le tag "c"

Le tag "c" permet d'indiquer que le mot est un mot faisant partie du code.

/// <summary>

/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>public class MaClasse{

}



III-B-7. Le tag "remarks"

Le tag "remarks" permet de mettre des remarques sur une classe.


fonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>/// <remarks>/// Une remarque fort interessante peut être placé ici./// </remarks>public class MaClasse{

}

III-B-8. Le tag "exception"

Le tag "exception" permet d'informer sur le(s) type(s) d'exception(s) que la fonction peutlever.Vous devez donner dans le tag, la condition pour que l'exception soit déclenchée. Lapropriété cref du tag permet de spécifier le type d'exception que vous documentez.

/// <summary>/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>/// <remarks>

/// Une remarque fort interessante peut être placé ici./// </remarks>public class MaClasse{




fonction ne fait rien .</returns>/// <exception cref="Type d'exception">Exception déclenchée

quand le programme plante ;-) </exception>

public int UneMethode(int a){

return a;}

}



III-B-9. Le tag "example"

Le tag "example" permet de spécifier le texte accompagnant un exemple d'utilisation d'uneméthode ou d'une classe.

/// <summary>

/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>/// <remarks>/// Une remarque fort interessante peut être placé ici./// </remarks>public class MaClasse{




fonction ne fait rien .</returns>/// <exception cref="Type d'exception">Exception déclenchée

quand le programme plante ;-) </exception>/// <example>Voila un exemple d'utilisation de la méthode

</example>public int UneMethode(int a){

return a;}

}

III-B-10. Le tag "code"

le tag "code" permet de marquer le texte qui suit comme étant du code.

/// <summary>/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>/// <remarks>

/// Une remarque fort interessante peut être placé ici./// </remarks>public class MaClasse{



tout.</param>



/// <returns>Valeur passée en argument non modifiée car lafonction ne fait rien .</returns>

/// <exception cref="Type d'exception">Exception déclenchéequand le programme plante ;-) </exception>

/// <example>Voila un exemple d'utilisation de la méthode/// <code>this.UneMethode(10);</code>/// </example>public int UneMethode(int a){

return a;}

}

III-B-11. Le tag "see"

Le tag "see" permet de créer un lien vers un élément documenté grâce au nom de cet

élément.Il doit être placé à l'intérieur d'un tag "summary" ou "remarks"

/// <summary>/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>/// <remarks>/// Une remarque fort interessante peut être placé ici./// <see cref="Main">Point d'entrée du programme</see>/// </remarks>public class MaClasse{

}

Si vous voulez faire pointer le lien vers un élément du framework il faut renseigner cref comme habituellement mais il faut dire au générateur de documentation que vous autorisezles lien vers la MSDN

III-B-12. Le tag "seealso"

Le tag "seealso" permet de créer un lien en bas de la page de documentation. Il est utilisépour renvoyer le lecteur à un complément d'information.

/// <summary>/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien./// </summary>/// <remarks>/// Une remarque fort interessante peut être placé ici./// <see cref="Main">Point d'entrée du programme</see>



/// </remarks>/// <seealso cref="System.Object">System.Object</seealso>public class MaClasse{

}

III-B-13. Le cas des listes

L'utilisation des listes est un peu plus compliqué que le reste.En effet il faut composer avec 4 tags différents. La liste doit être placée dans un tag"remarks".

/// <summary>/// Description complète de la classe. Généralement on donne lafonction de cette classe ainsi que ces particularités/// Possede une méthode <c>UneMethode</c> qui ne sert à rien.

/// </summary>/// <remarks>/// Une remarque fort interessante peut être placé ici./// <see cref="Main">Point d'entrée du programme</see>/// <list type="bullet" ou "number" ou "table">/// <listheader>/// <term>Le titre de la partie 1 dutableau (seulement en mode "table" </term>/// <description>Le titre de la partie 2 dutableau (seulement en mode "table" </description>/// </listheader>/// <item>/// <term>le terme à expliquer </item>/// <description> La description du terme</description>/// </item>/// </list>/// </remarks>public class MaClasse{

}

Il faut autant de balise item que vous voulez de ligne.Bien que l'utilisation de la liste soit un peu plus compliquée, ce n'est rien de bien méchant.

III-C. Comment générer la documentation ?

Afin de générer la documentation il vous faut générer le fichier Xml grâce au compilateur C#et à l'option /doc

mcs /out:unProgramme.exe /t:exe /doc ./*cs



L'autre façon de générer la documentation est d'utiliser votre EDI préféré afin de luidemander de générer le fichier Xml.Sous SharpDevelop : Onglets Projets -> Click droit sur le projet -> Options du projet ->Configuration -> Debug ou Release -> Génération de code -> Générer la documentationXml.

Génération du fichier Xml de documentation sous SharpDevelopSous Visual Studio 2005 Beta 2: Solution Explorer -> Build -> Xml Documentation File



Génération du fichier Xml de documentation sous Visual Studio 2005

Une fois que vous avez le fichier Xml vous pouvez utiliser le programme NDoc qui vouspermet de générer la documentation sous différents styles comme la MSDN, la javadoc ouencore LaTex.

III-C-1. Génération de la documentation avec NDoc

La génération de la documentation avec NDoc à partir du fichier XMl est très simple.Il vous suffit de lancer l'interface graphique de l'outil (NdocGui.exe) et de renseigner lesassemblies dont vous souhaitez générer la documentation.Pour ce faire il suffit de cliquer sur Add puis de sélectionner l'assembly. Si le fichier Xmlcorrespondant est dans le même répertoire que l'assembly, NDoc le sélectionneautomatiquement. Si ce n'est pas le cas il vous suffit de l'ajouter vous-même.



Séléction de l'assembly et de son fichier XmlIl ne vous reste plus qu'à lancer la génération par le biais du bouton dans la bar d'outils deNDoc.Le but n'étant pas de faire un tutoriel complet sur la génération de documentation avecNDoc, je ne vous parlerai donc pas des divers options possibles de NDoc.



IV. RemerciementJe tiens à remercier pharaonix et nightfall pour leur relecture.



La documentation du code en C#

La documentation du code en C# La documentation du code est particulièrement utile lors des évolutions et de la maintenance du

code. C# propose un mécanisme simple pour insérer dans le code des commentaires de

documentation qui seront traités pour réaliser une documentation technique.

Ces commentaires de documentation sont préfixés par ///

Ces commentaires sont saisis avant la déclaration des entités de type namespace, classe,

interface, champ, propriété, méthode, ou événement.

Ces commentaires peuvent utiliser des tags XML pour caractériser certaines informations. Ces

tags seront repris dans un document XML peut être généré à la demande par le compilateur. Il est

donc important que les commentaires de documentation saisis respectent le standard XML.

Ce fichier XML peut ensuite être traité pour par exemple produire des pages HTML grâce à une

feuille de style XSLT.

Microsoft a défini une liste de tags particuliers recommandés mais il est tout à fait possible

d'utiliser ces propres tags.

Les tags de documentation recommandés

Les tags XML suivants sont utilisables pour la documentation du code :

<c> <code> <example>

<exception> <include> <list>

<para> <param> <paramref>

<permission> <remarks> <return>

<see> <seealso> <summary>



<value>

Ces tags sont utilisables en fonction de l'entité documentée

Entité Tags utilisables

class <summary>, <remarks>, <seealso>

struct <summary>, <remarks>, <seealso>

interface <summary>, <remarks>, <seealso>

delegate <summary>, <remarks>, <seealso>, <param>, <returns>

enum <summary>, <remarks>, <seealso>

constructor <summary>, <remarks>, <seealso>, <param>, <permission>, <exception>

property <summary>, <remarks>, <seealso>, <value>, <permission>, <exception>

method<summary>, <remarks>, <seealso>, <param>, <returns>, <permission>,

<exception>

event <summary>, <remarks>, <seealso>

Le tag <c> Ce tag permet d'afficher le texte qu'il contient sous la forme de code

Syntaxe :

<c>texte</c>

Exemple :

/// resume de <c>maMethode</c>

Le tag <code>

Ce tag permet d'afficher le texte qu'il contient sous la forme de code. La différence avec le tag

<c> est que que le tag <code> est utilisé en multi-ligne.

Syntaxe :

<code>ligne1ligne2



</code>

Exemple

/// <code>

/// Class1 m = new Class1(); /// m.maMethode("Hello"); /// </code>

Le tag <example>

Ce tag permet de fournir un exemple d'utilisation de l'entité.

Syntaxe :

<example>texte</example

Exemple :

/// <example> /// Mise en oeuvre : /// <code> /// Class1 m = new Class1(); /// m.maMethode("Hello"); /// </code> /// </example>

Le tag <exception>

Ce tag permet de fournir des informations sur la levée d'une exception par une méthode

Le tag <list>

Ce tag permet de créer une liste d'élément avec puce, ou numéroté ou sous forme de tableau.

Syntaxe :

<list type="bullet" | "number" | "table">

<listheader><term>term</term><description>description</description>

</listheader><item>

<term>term</term><description>description</description>

</item></list>



Le tag <para>

Ce tag permet de créer un paragraphe à l'intérieur d'un tag.

Syntaxe

<para>texte</para>

Le tag <param>

Ce tag permet de fournir des informations sur un paramètre d'une méthode.

Syntaxe :

<param name='name'>description</param>

L'attribut name permet de préciser le nom du paramètre.

Exemple :

/// <param name="nom">nom de l'utilisateur</param>

Le tag <paramref>

Ce tag permet de faire référence à un paramètre dans le texte

Syntaxe :

<paramref name="name"/>

Le tag <remarks>

Ce tag permet de fournir des informations complémentaires sur une entité sous la forme d'une

remarque.

Syntaxe :

<remarks>description</remarks>

Exemple :

/// <remarks>remarque complémentaire.</remarks>

Le tag <return>



Ce tag permet de fournir de informations sur la valeur de retour d'une méthode

Syntaxe :

<returns>description</returns>

Exemple :

/// <returns>une chaine contenant une salutation</returns>

Le tag <see>

Ce tag permet de faire un lien vers un élément accessible dans le code.

Syntaxe :

<see cref="member"/>

L'attribut cref permet de préciser le membre.

Exemple :

/// <see cref="maMethode" />

Le compilateur vérifie l'accessibilité du membre précisé dans l'attribut cref : si celle ci échoué, il

émet un avertissement

Exemple :

Le commentaire XML sur 'ClassLibrary.Class1.maMethode(string)' possèdel'attributcref 'maMethode2df' et celui-ci est introuvable

Le tag <seealso>

Ce tag permet de faire un lien vers un élément qui sera inclus dans la section see also.

Syntaxe :

<seealso cref="member"/>

L'attribut cref permet de préciser le membre.

Exemple :

/// <seealso cref="ClassLibrary.MaCLasse2"/>



Le tag <summary>

Ce tag permet de fournir un résumé d'une entité.

Syntaxe

<summary>description</summary>

Exemple :

/// <summary> /// resume de maMethode /// </summary>

Le contenu de ce tag est utilisé par la fonction Intellisens de Visual Studio .Net pour afficher des

informations sur l'entité.

Le tag <value>

Ce tag permet de fournir des informations sur une propriété

Syntaxe :

<value>description</value>

Exemple :

/// <value> valeur entiere utilise dans les calculs /// </value>

Mise en ouvre avec Visual Studio .Net

Saisie des commentaires de documentation

Il suffit de saisir /// sur la ligne avant la déclaration de l'entité pour que Visual Studio .Net génère

automatiquement un squelette de commentaire de documentation en tenant compte de la

déclaration de l'entité.



Configuration du projet

Dans les propriétés du projet, sélectionner « Propriétés de configuration / générer» et modifier la

propriété « Fichier de documentation XML »

Il suffit de préciser un nom de fichier qui par convention se nomme nom_du_projet.xml.

A la compilation, ce fichier XML sera regénéré à partir du code source

Exemple :



<?xml version="1.0"?><doc>

<assembly><name>ClassLibrary</name>

</assembly><members>

<member name="T:ClassLibrary.Class1"><summary>Description resume de Class1.</summary>

</member><member name="M:ClassLibrary.Class1.maMethode(System.String)">

<summary>resume de maMethode</summary><param name="nom">nom de l'utilisateur</param><returns>une chaine contenant une salutation</returns>

</member></members>

</doc>

Utilisation de la documentation par V.S. .Net

Ce fichier va être utilisé par Visual Studio .Net pour fournir des informations dans l'éditeur de

code.

Exemple : lors de la sélection d'une méthode

Exemple : lors de sélection de la saisie d'un paramètre

L'inconvénient sous V.S. .Net une fois le fichier xml de documentation précisé pour un projet est

qu'il faut définir un commentaire de documentation pour toutes les entités du projet ainsi que leur

membre, sinon un avertissement est signalé pour chaque élément qui n'en possède pas.



Génération de la documentation au format Web

A partir du fichier XML, V.S. .Net peut générer la documentation sous la forme de page HTML :

un rapport Web de commentaire de code.

Pour demander la génération de la documentation au format HTML, il faut utiliser l'option «

Générer les pages web de documentation . » du menu « Outils ».

La boîte de dialogue permet de sélectionner les éléments pour lesquels la documentation doit être

généré, l'emplacement ou elle doit être stockée et des options.



Les pages web générées proposent un système de navigation dans les différents éléments

commentés.

L'outils NDoc

Microsoft ne propose pas d'outils satisfaisant pour exploiter les fichiers de documentations XML

générés par le compilateur C#.



Le projet open source NDoc propose une solution pour générer à partir de fichiers XML, une

documentation dans plusieurs formats grâce à des feuilles de style XSLT : HtmlHelp2, Javadoc

et MDSN. Deux autres formats sont proposés à titre expérimental (version 1.2.1303).

Le site web du projet se trouve à l'url : http://ndoc.sourceforge.net

Pour fonctionner l'outils HTML Help Workshop doit être installé sur la machine. il est livré avec

plusieurs outils de développement dont Visual Studio .Net ou peut être téléchargé

indépendament sur le site de Microsoft.

Pour lancer NDoc, il suffit d'exécuter l'application NDocGui.exe

http://ndoc.sourceforge.net/






Il faut ajouter un ou plusieurs assemblys en cliquant sur le bouton « add »



Il est aussi possible de laisser NDoc analyser directement une solution de Visual Studio .Net en

cliquant sur le bouton ou en utilisant l'option « New from Visual Studio Solution ». Il suffit

alors de sélectionner le fichier .sln.

Il faut ensuite sélectionner le type de documentation dans la liste déroulante.

Un certain nombre de paramètres peuvent être renseignés pour paramétrer la génération en

fonction du type de documentation demandée.

Pour demander la génération, il suffit de cliquer sur le bouton ou d'utiliser l'option « Build »

du menu « Documentation » ou enfin d'utiliser la combinaison de touche Ctrl+Maj+B.



Sommaire > Le langage C# > Opérations de base

Comment écrire des commentaires en C# ?

Quelles sont les signatures possibles pour la méthode Main ?

Comment faire référence à l'objet courant ?

Comment utiliser un mot-clé réservé comme nom de variable ou fonction ?

Comment vérifier qu'un objet est bien d'un certain type ? Comment déclarer et utiliser les tableaux à une dimension ?

Comment effectuer un décalage binaire sur un nombre ?

Comment récupérer la valeur par défaut d'un type ?

Comment calculer l'intervalle de temps entre deux dates ?

Comment définir une valeur null pour un type valeur ?

Comment passer un paramètre par référence à une méthode ?

Comment s'abonner à un évènement ?

Qu'est-ce qu'une méthode anonyme ?

Précédent Sommaire Suivant

Version hors-ligne (Miroir)

Comment écrire des commentaires en C# ? [haut]

auteurs : cardi, tomlev Il y a 2 manières d'écrire des commentaires de code en C# :

// ... Toute la ligne sera en commentaire.

/* ... */ Tout ce qui est contenu entre /* et */ sera en commentaire. Ce type de commentaire peut

s'étendre sur plusieurs lignes.

Il existe une troisième forme de commentaire, utilisée pour documenter le code :

/// <summary>/// description de la classe/// </summary>class MaClasse{

// ...}

http://faqcsharp.developpez.com/

http://faqcsharp.developpez.com/?page=lang



http://faqcsharp.developpez.com/?page=lang_base



http://faqcsharp.developpez.com/?page=lang_base#lang_base_CommentaireCode


http://faqcsharp.developpez.com/?page=lang_base#lang_base_DifferentSignatureMain


http://faqcsharp.developpez.com/?page=lang_base#lang_base_MotReserveObjetCourant


http://faqcsharp.developpez.com/?page=lang_base#lang_base_ReservedWordsLikeVarFunction


http://faqcsharp.developpez.com/?page=lang_base#lang_base_IsAsVerificationType


http://faqcsharp.developpez.com/?page=lang_base#lang_base_uni_dim_array


http://faqcsharp.developpez.com/?page=lang_base#lang_base_DecalageBits


http://faqcsharp.developpez.com/?page=lang_base#lang_base_DefaultValueOfType


http://faqcsharp.developpez.com/?page=lang_base#lang_base_DifferenceTimeBetweenDates


http://faqcsharp.developpez.com/?page=lang_base#lang_base_InitValueTypeNullable

http://faqcsharp.developpez.com/?page=lang_base#lang_base_refout


http://faqcsharp.developpez.com/?page=lang_base#lang_base_subscribe_event


http://faqcsharp.developpez.com/?page=lang_base#lang_base_method_ano


http://faqcsharp.developpez.com/?page=lang_class

ftp://ftp-developpez.com/dotnet/faq/csharp/faqdotnetcsharp.zip


http://dotnet.ftp-developpez.com/faq/csharp/faqdotnetcsharp.zip






http://www.developpez.net/forums/member.php?u=26308



http://www.developpez.net/forums/u30665/tomlev/









http://faqcsharp.developpez.com/?page=lang_class


















http://faqcsharp.developpez.com/



Une option du compilateur permet d'extraire tous les commentaires de documentation du code

dans un fichier XML, qui peut ensuite être utilisé par des outils pour générer des pages de

documentation.

lien : ComDoc

Quelles sont les signatures possibles pour la méthode Main ? [haut]

auteur : cardi

La méthode Main est le point d'entrée de tout programme. Il existe 4 signatures différentes :

class DifferentsMain{

// Méthode sans paramètres

// Ni code de retourpublic static void Main(){ }

// Méthode sans paramètres// Avec code de retourpublic static int Main(){ return 0; }

// Méthode avec paramètres// Mais sans code de retourpublic static void Main(params String[] param){ }

// Méthode avec paramètres// Et code de retourpublic static int Main(params String[] param){ return param.Length; }

}

Contrairement à ce que vous pourriez penser, il n'y a pas 6 signatures possibles mais bien 4 car il

n'est pas possible d'utiliser la classe de base Object à la place de String.

Comment faire référence à l'objet courant ? [haut]

auteurs : cardi, tomlev

En C#, il est possible d'accéder explicitement aux membres de l'objet courant par l'intermédiaire

du mot réservé this. Cela permet notamment de lever une ambiguïté si une variable locale ou un

paramètre porte le même nom qu'un membre de l'objet courant :

http://vincentlaine.developpez.com/tuto/dotnet/comdoc/




























class ExempleThis{

private String monString;

public ExempleThis(string monString)

{ this.monString = monString;}

}

Le mot-clé this permet également de faire référence à l'objet courant, par exemple pour le passer

à une autre classe :

class Parent{

private List<Enfants> _enfants = new List<Enfant>();

public IEnumerable<Enfant> Enfants{

get { return _enfants; }}

public Enfant AddEnfant(){

Enfant e = new Enfant(this); // On passel'objet courant en paramètre

_enfants.Add(e);return e;

}}

class Enfant{

public Enfant(Parent parent){

this.Parent = parent;}

public Parent Parent { get; private set; }}

Comment utiliser un mot-clé réservé comme nom de variable ou fonction ? [haut]


Bien que cela soit déconseillé, il est possible d'utiliser un mot-clé réservé en le préfixant du

caractère @ :

void @while()
















{int @class = 2007;

}

Comment vérifier qu'un objet est bien d'un certain type ? [haut]


Il existe 2 solutions pour déterminer si un objet est d'un type donné :

La première est d'utiliser le mot-clé is. Ce dernier renvoie vrai si l'objet est bien du type demandé

:

String monString = "Ceci est un test !";if (monString is String)

Console.WriteLine("monString est bien de type String !");elseConsole.WriteLine("monString n'est pas de type String !");

Une seconde solution est d'utiliser as. La différence est que as va tenter de faire le cast de l'objet

vers le type spécifié. Si le cast n'est pas valide, null sera renvoyé :

class Customer{ }class Vendor

{ }

public static void Main(){

Object obj = new Vendor();

Object testCustomer = obj as Customer;Object testVendor = obj as Vendor;

if (testCustomer == null)Console.WriteLine("L'objet testé n'est pas de type

Customer !");else

Console.WriteLine("L'objet testé est de type Customer!");

if (testVendor == null)Console.WriteLine("L'objet testé n'est pas de type

Vendor !");else

Console.WriteLine("L'objet testé est de type Vendor!");

}
















Notez que le mot-clé as ne peut être utilisé qu'avec un type référence, puisque les objets de type

valeur ne peuvent pas valoir null.

Comment déclarer et utiliser les tableaux à une dimension ? [haut]

auteurs : Thomas Lebrun, abelman

Pour utiliser un tableau, en C#, vous devez faire suivre le type des éléments du tableau par [].

Pour accéder aux éléments du tableau, vous devez le parcourir en utilisant les index (attention, le

premier indice des éléments d'un tableau commence à 0 et pas à 1)

public class Tableau{

// Tableau de type chaine

private string[] _TableauString;


// On définit la taille du tableau_TableauString = new string[3];

// On remplit le tableaufor (int i = 0; i < 3; i++){

_TableauString[i] = "Chaine " + i;}

// Affichage du contenu du tableaufor (int i = 0; i < 3; i++){

Console.Write("Case " + i);Console.WriteLine("Contenu: " + _TableauString[i]);

}}

}

Comment effectuer un décalage binaire sur un nombre ? [haut]


Vous pouvez effectuer un décalage à gauche ou droite d'un certain nombre de bits à l'aide des

opérateurs << et >> :

int value = 8;int res;





























Console.WriteLine("La valeur de départ vaut {0}", value);

// Décalage vers la gauche// res est multiplié par 2res = value << 1;Console.WriteLine("Après un décalage de 1 vers la gauche, res

vaut {0}", res);

// Décalage vers la droite// res est divisé par 2res = value >> 1;Console.WriteLine("Après un décalage de 1 vers la droite, res

vaut {0}", res);

// Décalage vers la gauche// res est multiplié par 4res = value << 2;Console.WriteLine("Après un décalage de 2 vers la gauche, res

vaut {0}", res);

lien : Opérateur << (MSDN)

lien : Opérateur >>

Comment récupérer la valeur par défaut d'un type ? [haut]


Le mot-clé default permet d'obtenir la valeur par défaut d'un type. Pour un type référence, la

valeur par défaut est toujours null. Pour un type valeur, la valeur par défaut est une instance du

type où tous les champs ont leur valeur par défaut (tous les octets à 0).

Console.WriteLine("Valeur par défaut de int : {0}",default(int) != null ? default(int).ToString() : "NULL");

Console.WriteLine("Valeur par défaut de string : {0}",default(string) != null ? default(string).ToString() : "NULL");

Ce mot-clé est particulièrement pratique quand on écrit une classe ou une méthode générique.

Comment calculer l'intervalle de temps entre deux dates ? [haut]


La différence entre 2 dates s'effectue à l'aide de l'opérateur -, qui est redéfini dans le type

DateTime pour renvoyer un objet de type TimeSpan (intervalle de temps).

Calculons le nombre de jours écoulés depuis la création de cette question :

DateTime DateCourante = DateTime.Now;DateTime DateCreationquestion = new DateTime(2007, 1, 3);

http://msdn.microsoft.com/fr-fr/library/a1sway8w.aspx



http://msdn.microsoft.com/fr-fr/library/xt18et0d.aspx

































TimeSpan Ts = DateCourante - DateCreationquestion;Console.WriteLine("Il s'est écoulé {0} jour(s) depuis la

création de cette question !", Ts.Days);

Notez que divers opérateurs arithmétiques sont également redéfinis dans les structures DateTimeet TimeSpan, si bien qu'on peut effectuer diverses opérations sur les dates.

DateTime - DateTime = TimeSpan

DateTime + TimeSpan = DateTime

DateTime - TimeSpan = DateTime

TimeSpan + TimeSpan = TimeSpan

DateTime + DateTime = impossible car cela n'a pas de sens

lien : System.TimeSpan (MSDN)

Comment définir une valeur null pour un type valeur ? [haut]


Un type valeur, par définition, ne peut pas être null : il a forcément une valeur. Il existe

cependant un type générique Nullable<T> qui permet d'englober un type valeur, et qui peut

valoir null :

// Entier non nullableint monInt1 = 42;

// Entier nullableNullable<int> monInt2 = null;

// Entier nullable, notation abrégéeint? monInt3 = null;

// Conversion implicite de int vers Nullable<int>monInt2 = monInt1;

// Copie d'un Nullable<int> vers un intif (monInt2.HasValue){

// Pas de conversion implicite de Nullable<int> vers

int, on utilise la propriété ValuemonInt1 = monInt2.Value;

}

lien : System.Nullable<T> (MSDN)

http://msdn.microsoft.com/fr-fr/library/system.timespan.aspx











http://msdn.microsoft.com/fr-fr/library/b3h38hb0.aspx














Comment passer un paramètre par référence à une méthode ? [haut]

auteurs : Thomas Lebrun, tomlev

En utilisant les mot-clés ref et out. La différence entre ref et out est la suivante :

Avec ref , l'initialisation du paramètre est de la responsabilité du code appelant. La

méthode n'est pas obligée de modifier la valeur du paramètre.

Avec out , l'initialisation de la variable est de la responsabilité de la méthode, qui doit

obligatoirement lui affecter une valeur avant de se terminer. Le code appelant n'est pas

obligé de l'initialiser.

Voici un exemple pour clarifier tout ça :

class TestRef{

public void TestRef(ref int i){

if (i < 0)i = 0;

}

public void TestOut(out int j){

j = 5;}


// On initialise l'entier aint a = -3;// On le passe en paramètre à la fonction, par référenceTestRef(ref a);Console.WriteLine("a vaut maintenant 1");

// Utilisation de outint b;// On passe b en paramètre sans l'avoir initialiséTestOut(b);

Console.WriteLine("b vaut maintenant 5");}

}

Comment s'abonner à un évènement ? [haut]

auteur : tomlev

Il est très facile de s'abonner à un évènement de l'interface graphique à l'aide du designer, mais

qu'en est-il quand on veut le faire soi-même dans le code ? Il suffit pour cela d'utiliser l'opérateur

+= :

























monObjet.MonEvenement += new EventHandler(monObjet_MonEvenement);

...

private void monObjet_MonEvenement(object sender, EventArgs e){Console.WriteLine("MonEvenement s'est produit !");

}

Notez qu'on indique le type de delegate défini pour l'évènement (EventHandler dans ce cas). La

signature (type de retour et types des paramètres) de la méthode utilisée pour s'abonner doit

correspondre à la signature de ce delegate.

Depuis C# 2, il n'est plus nécessaire de spécifier le type de delegate, on peut donc écrire

simplement :

monObjet.MonEvenement += monObjet_MonEvenement;

Cependant la règle de correspondance des signatures s'applique toujours.

Pour se désabonner d'un évènement, on utilise l'opérateur -= :

monObjet.MonEvenement -= monObjet_MonEvenement;

Qu'est-ce qu'une méthode anonyme ? [haut]

auteurs : dev01, tomlev

Une méthode anonyme est une méthode sans nom qui peut être créée à l'intérieur d'une autre

méthode. Le résultat obtenu est en fait un delegate, qui peut être affecté à une variable ou passé

en paramètre d'une méthode.Voyons un exemple plus parlant :

monButton.Click += delegate{

MessageBox.Show("Une méthode anonyme");};

On peut aussi spécifier les paramètres au cas où on aurait besoin de les utiliser :

monButton.Click += delegate(object sender, EventArgs e){

MessageBox.Show("Une méthode anonyme");};

La version 3 de C# introduit une nouvelle syntaxe pour déclarer des méthodes anonymes,

appelée "expression lambda" :
















monButton.Click += (sender, e) =>

{MessageBox.Show("Une méthode anonyme");

};

lien : L'article de Louis-Guillaume Morand sur les nouveauté du framework 2.0

lien : Les méthodes anonymes en C# (MSDN)

http://lgmorand.developpez.com/dotnet/framework2/#L1.1



http://msdn.microsoft.com/fr-fr/library/0yw3tz5k.aspx





Documents

Bien Commenter Et Documenter Son Code en C