Commentaires de code

Lorsque vous écrivez du code, vous allez vite vous rendre compte que chaque mot ou caractère a une signification particulière. Par exemple, on trouve de nombreux mots-clé en C#, comme class, namespace, public et bien plus encore. Vous allez également remarquer que le compilateur s'assure que vous utilisez ces mots-clé, vos variables et vos fonctions correctement. Le C# est un langage strict, le compilateur est là pour vous aider à écrire votre programme comme il devrait l'être. Cependant, vous avez une unique possibilité d'écrire tout ce que vous voulez comme vous voulez avec le concept des commentaires de code

Le concept de commentaire de code est universel, vous avez donc sûrement rencontré des commentaires dans les programmes que vous avez vu que ce soit en C# ou un autre langage de programmation. La manière d'écrire les commentaires peut varier, voyons comment les utiliser dans votre code en C#.

Commentaires sur une ligne

La manière la plus basique en C# est le commentaire sur une seule ligne. Comme le nom l'indique, il transforme une ligne en commentaire. Voyons à quoi cela ressemble :

// My comments about the class name could go here...
class Program
{
    ......

Voilà, il suffit d'ajouter deux slashs (//) en début de ligne et cette ligne que le compilateur doit analyser devient une ligne que le compilateur ignore complétement. Il est possible d'utiliser cette méthode plusieurs fois à la suite pour écrire un commentaire sur plusieurs lignes comme ceci :

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Commentaires sur plusieurs lignes

Si vous souhaitez écrire un commentaire sur plusieurs lignes, utiliser la manière dédiée du C# a du sens. Au lieu de préfixer chaque ligne, il faut seulement écrire une séquence de début et de fin commentaire, tout ce qui se trouve entre ces deux marques sera considéré comme commentaire :

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Utilisez la séquence de commencement composée d'un slash étoile (/*), écrivez ce que vous voulez, sur plusieurs lignes ou non, et terminez avec la séquence de fin composée d'une étoile slash (*/). Entre ces marqueurs, écrivez ce que vous voulez.

Comme pour à peu près tous les sujets reliés à la programmation, l'utilisation de plusieurs commentaires d'une ligne ou d'un seul commentaire d'une seule ligne est souvent débattue. Personnellement, j'utilise les deux, en fonction de la situation. En fin de compte, c'est à vous de choisir !

Commentaires de documentation .

Les commentaires de documentation ( parfois appelés Commentaires de Documentation XML ) sont des commentaires standard auxquels on intègre du XML . Ils peuvent , comme les commentaires standard , prendre deux formes : Une ou plusieurs lignes . Leur syntaxe est la même que pour les commentaires standard à ceci prés que l'on ajoute un caractère en plus . Ainsi les commentaires de documentation XML sur une ligne nécessitent trois slashes (///) au lieu de deux tandis que leur variante à plusieurs lignes nécessite l'ajout d'un asterisk au début du commentaire . Voyons ce que cela donne :

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Ici vous pouvez voir les deux variantes- monoligne et multilignes. Le résultat est le même, mais la première variante tend à être plus utilisée pour les commentaires de documentation.

Documenter vos types et leurs membres dans des commentaires de documentation est un sujet assez vaste, c'est pourquoi cela sera couvert plus en détails dans un article ultérieur, mais pour l'instant, vous savez à quoi ils ressemblent !

Commentaires de code & la liste de tâches .

Si vous utilisez Visual Studio vous pouvez facilement retrouver vos commentaires de code ; Dans la fenêtre Liste de tâches / Task List ( accédez au menu View > Task List) vos commentaires apparaîtront si ils utilisent la syntaxe des Commentaires de Liste de Tâches .

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Ainsi , si un commentaire mono-ligne est suivi par le mot-clé TODO ou HACK il apparaîtra dans la liste de tâches de Visual Studio sous cette forme :

D'autres mot-clé sont disponibles selon la version de Visual Studio que vous utilisez :

• TODO
• HACK
• NOTE
• UNDONE

Vous pouvez même créer vos propres mot-clé si vous le souhaitez . Un tutoriel est disponible en ouvrant ce lien..

Résumé

Les commentaires sont extrêmement utiles pour documenter et clarifier votre code ou pour expliquer aux autres développeurs comment il fonctionne . C'est aussi une manière simple pour faire des tests rapides - remplacez une ligne de code en commentant la ligne originale pour voir comment les choses fonctionnent . Si vous n'êtes pas satisfait du résultat effacez la nouvelle ligne et réactivez la ligne originale en enlevant les commentaires .

Par ailleurs l'utilisateur final ne pourra pas accéder à vos commentaires - comme nous l'avons vu précédemment ils seront complètement ignorés par le compilateur et ne seront de ce fait jamais inclus dans la DLL finale ou le fichier EXE que vous compilerez . Les commentaires de code sont un espace personnel et privé en programmation , utilisez les donc librement .