Les commentaires en C : // et /* */ expliqués

Un commentaire est du texte que le compilateur jette. Il existe uniquement pour les personnes qui liront le code plus tard, dont l'une est généralement vous. Le C offre deux formes, et savoir quand chacune est le bon outil prend environ deux minutes.

Les deux formes

#include <stdio.h>

int main(void) {
    // Un commentaire d'une ligne : tout ce qui suit // jusqu'a la fin de la ligne.

    /* Un commentaire de bloc.
       Il peut s'etendre sur autant de lignes que vous voulez
       et ne se termine qu'au marqueur fermant. */

    printf("Les commentaires n'atteignent jamais la sortie.\n");  // ils peuvent aussi suivre du code
    return 0;
}

Lancez-le : la sortie tient sur une ligne. Les deux commentaires ont été supprimés avant même que le compilateur n'analyse le programme - ils ne coûtent rien à l'exécution et n'ajoutent rien à l'exécutable.

// court jusqu'à la fin de la ligne physique. Rien ne peut le suivre sur cette ligne, donc ceci ne fonctionne pas comme on pourrait le croire :

int x = 5;  // met x a cinq  int y = 6;   /* y n'est jamais declare */

/* ... */ se termine au premier */, où qu'il soit. Il peut commencer et finir au milieu d'une ligne, ce qui est parfois utile :

int total = price /* avant taxes */ + shipping;

Pourquoi deux styles existent

/* */ est le C originel, de 1972. // vient du C++ et n'a été officiellement ajouté au C qu'en C99. Cette histoire explique quelque chose que vous remarquerez en lisant du code ancien : les bibliothèques écrites pour rester portables vers C89 utilisent /* */ même pour des commentaires d'une ligne, car // ne compilerait pas sur les vieilles chaînes d'outils qu'elles prenaient encore en charge.

Aujourd'hui, tous les compilateurs que vous êtes susceptible d'utiliser acceptent les deux. Utilisez // pour les remarques ordinaires et /* */ quand un commentaire s'étend réellement sur plusieurs lignes. Si vous visez un très vieux compilateur embarqué, vérifiez avant de compter sur //.

Les commentaires ne s'imbriquent pas

C'est le seul vrai piège :

/* Desactiver cette section pour l'instant
   int a = compute();
   /* le helper classique - a surveiller */
   int b = a * 2;
*/

Le commentaire de bloc se termine au premier */, celui de la ligne 3. Les lignes 4 et 5 redeviennent alors du code actif, et le */ final de la ligne 6 est une erreur de syntaxe. Le message du compilateur pointe la dernière ligne et n'aide en rien sur la cause.

La solution est d'utiliser le préprocesseur, qui gère l'imbrication :

#if 0
    int a = compute();
    /* le helper classique - a surveiller */
    int b = a * 2;
#endif

#if 0 n'est jamais vrai, donc le préprocesseur supprime tout jusqu'à #endif avant que le compilateur ne le voie. Cela survit aux commentaires, aux guillemets et aux autres blocs #if internes, et c'est facile à rechercher au moment du nettoyage.

Commenter du code pendant le débogage

Retirer temporairement une ligne est l'usage quotidien le plus courant des commentaires. Quand un programme se comporte mal, désactiver une instruction à la fois vous dit laquelle compte.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("etape %d : total = %d\n", i, total);  /* activer pour tracer */
    }

    printf("Total final : %d\n", total);
    return 0;
}

Décommentez le printf et relancez pour voir la boucle construire sa réponse. Tracer avec des affichages n'est pas élégant, mais en C c'est rapide et cela marche toujours - un débogueur vous en dit plus, et un printf vous dit quelque chose tout de suite.

Deux habitudes empêchent que cela devienne le désordre. Supprimez le code commenté avant de le valider ; le gestionnaire de versions se souvient de l'ancienne version à votre place. Et quand vous laissez délibérément une ligne désactivée, expliquez pourquoi dans une note à côté.

Les commentaires de documentation

Un commentaire de bloc au-dessus d'une fonction est l'endroit où vous expliquez ce qu'elle fait, ce que ses paramètres signifient, et tout ce qui est surprenant à son sujet.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Convertit une temperature en degres Celsius vers des degres Fahrenheit.
 *
 *   c : la temperature d'entree, en Celsius
 *
 * Renvoie la temperature equivalente en Fahrenheit.
 */
double celsius_to_fahrenheit(double c) {
    return c * 9.0 / 5.0 + 32.0;
}

int main(void) {
    printf("100C = %.1fF\n", celsius_to_fahrenheit(100.0));
    printf("0C   = %.1fF\n", celsius_to_fahrenheit(0.0));
    return 0;
}

Des outils comme Doxygen lisent des commentaires structurés de ce type et génèrent une documentation de référence. Le style propre à Doxygen utilise /** ... */ avec les balises @param et @return :

/**
 * Convertit des Celsius en Fahrenheit.
 * @param c temperature en Celsius
 * @return la meme temperature en Fahrenheit
 */
double celsius_to_fahrenheit(double c);

L'un ou l'autre convient pour votre propre code. Ce qui compte, c'est que le commentaire vive à côté de la déclaration que les gens lisent - dans le fichier d'en-tête, typiquement - plutôt qu'enfoui dans l'implémentation.

Ce qui mérite un commentaire

La règle qui survit au contact des vraies bases de code : commentez le pourquoi, pas le quoi.

i++;  // incremente i          <- ne dit rien que le code ne disait deja

/* Sauter le BOM : les fichiers exportes par l'ancien systeme commencent par
   trois octets qui ne font pas partie des donnees. */
offset += 3;

Le second commentaire contient une information qui n'est nulle part dans le code. Le premier est du bruit qui finira par contredire la ligne qu'il décrit, car les commentaires ne sont pas mis à jour quand le code change.

Ce qui mérite réellement un commentaire, spécifiquement en C :

• À qui appartient cette mémoire. Si une fonction renvoie un pointeur que l'appelant doit free, dites-le. Le C n'a aucun moyen d'exprimer cela dans le type.
• Unités et plages. int timeout; est ambigu - secondes ou millisecondes ?
• Une correction non évidente. Pourquoi la boucle s'arrête à n - 1, pourquoi ce cast est sûr, pourquoi le tampon fait 256 octets.
• L'étrangeté délibérée. Du code qui ressemble à un bug sans en être un attire les « corrections » des futurs lecteurs s'il n'est pas étiqueté.

#include <stdio.h>
#include <string.h>

int main(void) {
    char name[32];  /* 31 caracteres plus le '\0' terminal */

    /* strncpy N'AJOUTE PAS de terminateur si la source remplit le tampon,
       nous en ecrivons donc un nous-memes. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

    printf("Nom : %s\n", name);
    return 0;
}

Ce commentaire mérite sa place : la ligne en dessous semble redondante et ne l'est pas.

Les commentaires dans les chaînes n'en sont pas

Un dernier détail. Les marqueurs de commentaire n'ont aucune signification particulière à l'intérieur d'un littéral de chaîne ou d'une constante caractère :

#include <stdio.h>

int main(void) {
    printf("Progression : 50%% // pas un commentaire\n");
    printf("Le chemin est /* juste du texte */\n");
    return 0;
}

Les deux lignes s'affichent en entier. Le compilateur découpe les chaînes en jetons avant de chercher les commentaires, donc // entre guillemets n'est que deux caractères. (Le %% de la première ligne est la façon d'afficher un signe pourcent littéral avec printf - % seul commence un spécificateur de format.)