commentaires

Qu’est-ce qu’un commentaire ?

Les commentaires sont des textes explicatifs insérés dans le code source pour aider les développeurs à comprendre la logique du programme. Ils ne font pas partie du code exécutable, et le compilateur ignore intégralement leur contenu lors de la compilation.

Les commentaires sont aussi très utiles pour déboguer et identifier les erreurs. Si vous ne parvenez pas à localiser l’origine d’un bug, vous pouvez mettre en commentaire les segments de code suspects : le compilateur les omettra, ce qui permet d’isoler pas à pas la source du problème.

Les commentaires sont comparables aux notes manuscrites que nous ajoutions dans nos manuels scolaires ; ces compléments d’information rendent beaucoup plus simple la compréhension du contenu principal.

Types de commentaires

Type de commentaire	Marqueur d’ouverture	Marqueur de fermeture	Règles essentielles
Commentaire sur une seule ligne Single-line	//	Fin de la ligne courante	Ne s’applique qu’à la ligne entière ; tout ce qui suit // sur la même ligne est ignoré
Commentaire de bloc Delimited	/*	*/	Couvre plusieurs lignes ou un fragment au sein d’une ligne ; l’imbrication est interdite
Commentaire de documentation Documentation	///	Fin de la ligne courante	Intègre des balises XML, utilisé pour générer automatiquement la documentation API du projet

1. Commentaires sur une seule ligne //

1. Tout ce qui débute par // jusqu’à la fin de la ligne actuelle est ignoré par le compilateur ;
2. Peut être placé au début d’une ligne ou après le code fonctionnel ;
3. Aucune contrainte d’imbrication, pas de conflit syntaxique avec les blocs /* */.

// Commentaire en début de ligne : déclarer une variable numérique
int num = 10; // Commentaire après le code : stocke la valeur 10
// int temp = 99; // Ligne entière mise en commentaire pour le débogage ; désactive temporairement le code sans le supprimer, facile à restaurer par la suiteLangage du code : JavaScript (javascript)

2. Commentaires de bloc /* */

1. Nécessite une paire de marqueurs ouverture-fermeture ; tout le contenu entre /* et */ est ignoré ;
2. Prend en charge la couverture de plusieurs lignes complètes et les commentaires partiels au sein d’une ligne ;
3. Il est strictement interdit d’imbriquer des blocs de commentaires. Le compilateur termine le commentaire au premier */ rencontré, tout marqueur */ isolé restant provoque une erreur de syntaxe.

Exemple basique

/*
Exemple de commentaire de bloc multi-lignes
Le compilateur saute tout ce qui se trouve à l'intérieur
On peut écrire du texte sur un nombre illimité de lignes
*/
string str = "Test";Langage du code : JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Langage du code : JavaScript (javascript)

L’imbrication entraîne une erreur de compilation

Lorsqu’un bloc de commentaire est placé à l’intérieur d’un autre, le dernier marqueur de fermeture n’a pas de marqueur d’ouverture correspondant, ce qui cause l’échec de la compilation.

Commentaires partiels en ligne

Ne masque qu’un fragment de code ; dans l’exemple ci-dessous, la variable a est entièrement mise en commentaire.

int /*a,*/ b; 
// Équivaut à int b ; le segment « a, » entre les marqueurs est exclu de l'exécutionLangage du code : JavaScript (javascript)

Exemple invalide de bloc imbriqué

Génère une erreur syntaxique

/* Début du commentaire externe
    /* Commentaire imbriqué interne (traité uniquement comme texte brut, sans effet) */
// Le premier */ ci-dessus ferme le bloc externe, le dernier */ n'a pas d'ouverture associée et rompt la syntaxe
*/Langage du code : JavaScript (javascript)

Le symbole /* dans un // ne déclenche pas de bloc de commentaire

Les marqueurs de bloc sont ici considérés comme du texte ordinaire à l’intérieur du commentaire simple et ne fonctionnent pas en tant que tel.

// Ceci est un commentaire simple /* le /* ici n'est qu'un caractère texte, il ne démarre pas de bloc
int x = 5;
/* Ouverture d'un bloc de commentaire */ // Le bloc se termine ici, le // suivant fonctionne normalementLangage du code : JavaScript (javascript)

3. Commentaires de documentation ///

1. Ressemble aux commentaires simples, marqué par trois barres obliques consécutives /// ;
2. Prend en charge des balises XML intégrées ; les IDE et outils les lisent pour produire une documentation de référence API ;
3. S’écrit généralement au-dessus des classes, méthodes et propriétés pour documenter les interfaces publiques.

/// <summary>
/// Classe principale, point d'entrée de l'application
/// </summary>
class Program
{
    /// <summary>
    /// Méthode d'entrée du programme
    /// </summary>
    /// <param name="args">Tableau des arguments de la ligne de commande</param>
    static void Main(string[] args)
    {

    }
}Langage du code : JavaScript (javascript)

Synthèse

1. Les blocs de commentaires /* */ ne supportent pas l’imbrication ; l’analyse du commentaire s’arrête immédiatement au premier */ ;
2. Les commentaires simples // ne s’appliquent qu’à leur ligne, ne débordent pas sur les lignes voisines ; tout /* à l’intérieur est interprété comme un caractère littéral ;
3. La syntaxe et le comportement des commentaires simples et blocs en C# sont identiques à C/C++ ;
4. Règle de rédaction des commentaires : ne pas répéter ce que fait littéralement le code, privilégier l’explication du but métier et de la logique de conception pour faciliter la maintenance future. Un commentaire qui ne fait que recopier un nom de variable n’a aucune utilité.
5. Courte explication sur une ligne, désactivation temporaire d’une ligne de code → utiliser //
6. Désactivation groupée de plusieurs lignes, masquage partiel d’un fragment dans une ligne → utiliser /* */
7. Documenter les interfaces de classe/méthode, générer automatiquement la documentation du projet → utiliser ///

* Comment générer la documentation

La section suivante est une référence. Les commentaires de documentation sont principalement utilisés sur des projets de grande envergure ; pendant l’apprentissage, il suffit de comprendre que cette fonctionnalité existe.

Manipulation sous Visual Studio

1. Faites un clic droit sur le projet → Propriétés → onglet Générer (Build) ;
2. Cochez la case : Generate XML documentation file (Générer un fichier de documentation XML) ;
3. Chemin de sortie par défaut : bin\Debug\NomDuProjet.xml, un chemin personnalisé peut être défini ;
4. Cochez pour All Configurations (Toutes les configurations) afin que Debug et Release produisent tous deux le fichier XML ;
5. Régénérez le projet ; un fichier XML complet regroupant tous les commentaires apparaît dans le dossier cible.

Configuration en ligne de commande .NET CLI (sans Visual Studio)

Ouvrez le fichier .csproj du projet et ajoutez le nœud suivant :

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>Langage du code : HTML, XML (xml)

Exécutez la commande de génération :

dotnet build

Rôle du fichier XML

Ce fichier XML stocke l’intégralité du contenu des balises <summary>、<param>、<returns> et constitue la source de données pour générer la documentation de référence. Par ailleurs, Visual Studio lit ce fichier pour afficher les commentaires dans les infobulles d’IntelliSense au survol de la souris.

Autres outils de documentation

DocFX officiel Microsoft (recommandé par Microsoft, génère des sites statiques de documentation au format HTML)

Sandcastle (outil historique Microsoft pour créer des fichiers d’aide hors ligne au format CHM)

Outils légers tiers (exemple : Doxygen)

Présentation complète des trois syntaxes de commentaires