Programmation C sharp/Les commentaires

Tout bon programme a des fichiers sources bien commentés pour expliquer comment cela fonctionne et pourquoi certains choix ont été faits. Ce qui évite une perte de temps lorsque le code source est repris et modifié, soit par un autre développeur, soit par l'auteur qui ne se souvient pas forcément de son projet s'il n'y a pas touché depuis longtemps.

Bloc de commentaire

Un bloc de commentaire est délimité par les signes slash-étoile /* et étoile-slash */ comme en Java et en C++. Exemple :

/*
    Un commentaire explicatif
    sur plusieurs lignes...
*/

Les blocs ne peuvent être imbriqués car dès que le compilateur trouve slash-étoile /*, il recherche la première occurrence d'étoile-slash */ terminant le commentaire.

Ce code contient une erreur volontaire !

/* : début du commentaire

    /* : ignoré

    fin du commentaire : */

erreur ici car le commentaire est fini : */

Commentaire de fin de ligne

Un commentaire de fin de ligne débute par un double slash // et se termine au prochain retour à la ligne. Exemple :

x++;  // augmenter x de 1

Le commentaire ne doit pas paraphraser le code, mais expliquer le rôle de cette partie du code, comme par exemple :

x++;  // décaler le point d'un pixel vers la droite

Astuce : Visual Studio utilise ce type de commentaire pour les commandes commenter/décommenter le groupe de lignes sélectionnées (raccourcis claviers : CtrlE C pour commenter, CtrlE U pour décommenter, ou CtrlK C et CtrlK U avec les versions de Visual Studio .NET antérieures à 2005).

Commentaire de documentation

Le langage C# utilise une forme spéciale des commentaires pour documenter les classes. Ces commentaires commencent par un triple slash /// et se terminent au prochain retour à la ligne. Alternativement, ils peuvent être encadrés par /** et */.

Le contenu de ces commentaires est au format XML. Il est possible d'utiliser plusieurs lignes. Cette documentation se rapporte toujours à un des éléments de la déclaration qui suit.

Exemple :

/// <summary>
/// Une classe pour démontrer
/// les commentaires de documentation
/// </summary>
public class Exemple
{
    ...
}

Certaines balises XML sont standards, mais il est possible d'utiliser des balises supplémentaires. Pour plus de détails, voir le chapitre nommé Documentation XML des classes.