Maîtriser les commentaires C# : Types, bonnes pratiques et documentation XML

Commentaires C#

Dans cet article, nous allons apprendre les commentaires C#, les différents styles de commentaires, et pourquoi et comment les utiliser efficacement dans un programme.

Les commentaires sont l'élément vital d'un code lisible. Ce sont des annotations lisibles par l'homme qui expliquent l'intention, clarifient la logique complexe et documentent les décisions de conception. Le compilateur les ignore complètement, donc ils n'affectent pas les performances à l'exécution.

Selon la documentation officielle de Microsoft, C# prend en charge trois styles de commentaires principaux :

1. Commentaires sur une seule ligne (//)
2. Commentaires sur plusieurs lignes (/* */)
3. Commentaires de documentation XML (///)

---

Commentaires sur une seule ligne

Les commentaires sur une seule ligne commencent par une double barre oblique // et s'étendent jusqu'à la fin de la ligne. Tout ce qui suit // est ignoré par le compilateur.

int a = 5 + 7; // Addition de 5 et 7

Ici, Addition de 5 et 7 est le commentaire.

Exemple 1 : Utilisation d'un commentaire sur une seule ligne

// Programme Hello World
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) // L'exécution commence par la méthode Main
        {
            // Affiche Hello World
            Console.WriteLine("Hello World!");
        }
    }
}

Le programme ci-dessus contient trois commentaires sur une seule ligne :

// Programme Hello World
// L'exécution commence par la méthode Main
// Affiche Hello World

Bien que vous puissiez placer un commentaire sur la même ligne que le code, la bonne pratique consiste à garder les commentaires sur des lignes séparées pour éviter l'encombrement.

---

Commentaires sur plusieurs lignes

Les commentaires sur plusieurs lignes commencent par /* et se terminent par */. Ils peuvent s'étendre sur plusieurs lignes, ce qui les rend idéaux pour les explications en bloc ou la désactivation temporaire de blocs de code.

Exemple 2 : Utilisation d'un commentaire sur plusieurs lignes

/* Ceci est un programme Hello World en C#.
Ce programme affiche Hello World. */
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            /* Affiche Hello World */
            Console.WriteLine("Hello World!");
        }
    }
}

Le programme inclut deux commentaires sur plusieurs lignes :

/* Ceci est un programme Hello World en C#. Ce programme affiche Hello World. */
/* Affiche Hello World */

Notez qu'un seul bloc /* … */ peut remplacer un commentaire sur une seule ligne lorsque la brièveté est souhaitée.

---

Commentaires de documentation XML

Les commentaires de documentation XML commencent par trois barres obliques /// et permettent aux développeurs d'incorporer des métadonnées structurées directement dans le code. Ces commentaires sont extraits par des outils comme Visual Studio pour générer des fichiers de documentation XML externes, qui peuvent être utilisés par les IDE pour fournir des info-bulles IntelliSense et par les générateurs de documentation.

Si vous êtes nouveau dans XML, voir Qu'est-ce que XML ?.

Exemple 3 : Utilisation d'un commentaire de documentation XML

/// <summary>
/// Ceci est un programme hello world.
/// </summary>
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            Console.WriteLine("Hello World!");
        }
    }
}

Le commentaire XML dans l'exemple est :

/// <summary>
/// Ceci est un programme hello world.
/// </summary>

Le fichier XML généré ressemblerait à :

<?xml version="1.0"?>
<doc>
<assembly>
<name>HelloWorld</name>
</assembly>
<members>
</members>
</doc>

Pour des informations plus approfondies, visitez Commentaires de documentation XML.

---

Utiliser les commentaires correctement

Les commentaires efficaces clarifient l'intention sans encombrer le code. Sur-commenter peut obscurcir la logique, tandis que sous-commenter peut rendre la maintenance difficile.

Considérez cet exemple :

// Affiche Hello World
Console.WriteLine("Hello World");

Ajouter un commentaire ici est redondant ; le code s'explique de lui-même. Au lieu de cela, utilisez les commentaires pour :

• Expliquer des algorithmes non évidents ou la logique métier.
• Mettre en évidence des hypothèses, cas limites ou pièges potentiels.
• Décrire brièvement le but d'un bloc, en se concentrant sur le « pourquoi » plutôt que le « comment ».

Rappelez-vous : des commentaires concis et pertinents sont la marque des bases de code professionnelles.