Commentaires en C++ : une ligne // et multiligne /* */

À quoi servent les commentaires

Un commentaire est du texte dans votre code source que le compilateur C++ ignore complètement. Il n'atteint jamais le programme compilé - il existe uniquement pour les personnes qui lisent le code. Vous utilisez les commentaires pour expliquer pourquoi quelque chose est fait d'une certaine manière, pour laisser des rappels ou pour désactiver temporairement du code sans le supprimer.

En vous appuyant sur la syntaxe C++ que vous connaissez déjà, les commentaires font partie des rares choses que vous pouvez placer presque n'importe où et que le compilateur ignorera tout simplement. C++ en a deux sortes : sur une ligne (//) et de bloc multiligne (/* */).

Commentaires sur une ligne

Deux barres obliques (//) démarrent un commentaire qui court jusqu'à la fin de la ligne courante. Le compilateur ignore tout depuis le // jusqu'au saut de ligne.

#include <iostream>
using namespace std;

int main() {
    // Affiche un message d'accueil dans la console
    cout << "Hello, C++!" << endl;

    int score = 90; // un commentaire peut aussi se placer après du code
    cout << score << endl;
    return 0;
}

Remarquez que le deuxième commentaire partage une ligne avec du code réel. Tout ce qui est avant le // s'exécute toujours ; seule la partie qui le suit est ignorée. C'est le style de commentaire le plus courant pour de courtes notes.

Commentaires de bloc multilignes

Quand votre note s'étend sur plusieurs lignes, un commentaire de bloc est plus propre que de préfixer chaque ligne par //. Un commentaire de bloc commence par /* et se termine par */. Tout ce qui se trouve entre les deux - quel que soit le nombre de lignes - est ignoré.

#include <iostream>
using namespace std;

int main() {
    /*
     * Ce programme montre un commentaire de bloc.
     * Les astérisques en début de chaque ligne ne sont qu'une
     * convention de lisibilité - ils ne sont pas obligatoires.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

Les caractères * alignés le long du bord sont une convention de style, pas une règle. Les seules parties qui comptent réellement sont le /* d'ouverture et le */ de fermeture. Un commentaire de bloc peut même se trouver au milieu d'une ligne - int x = 5 /* width */ + 2; est valide - même si cela devient vite difficile à lire.

Commenter du code

Les commentaires sont la façon standard de désactiver du code pendant que vous expérimentez, sans le supprimer. Utilisez // pour une seule ligne, ou un commentaire de bloc pour désactiver plusieurs lignes à la fois.

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

Exécutez-le et vous ne verrez s'afficher que les deux lignes « runs ». Les instructions cout mises en commentaire sont invisibles pour le compilateur.

Le piège de la non-imbrication

Un piège qui surprend les débutants : les commentaires de bloc ne s'imbriquent pas. Le premier */ ferme le commentaire, quel que soit le nombre de /* qui le précèdent. Vous ne pouvez donc pas envelopper un bloc /* ... */ à l'intérieur d'un autre bloc /* ... */ - le */ interne met fin à tout, et ce qui suit redevient du code (généralement une erreur de syntaxe).

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

Le commentaire externe se termine au */ qui suit the width, donc le reste n'est plus en commentaire et le compilateur bute sur le */ final. Lorsque vous devez désactiver une zone qui contient déjà des commentaires de bloc, utilisez plutôt // sur chaque ligne. La plupart des éditeurs activent et désactivent les commentaires de ligne sur toute une sélection avec un seul raccourci clavier, ce qui contourne entièrement le problème.

Bons commentaires vs. bruit

Un commentaire doit expliquer quelque chose que le code ne peut pas dire de lui-même. Les commentaires qui ne font que reformuler le code ajoutent de l'encombrement et ont tendance à devenir obsolètes à mesure que le code change.

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

Efforcez-vous de rendre le code lisible grâce à des noms clairs et une bonne structure, et réservez les commentaires au pourquoi : l'intention, les compromis, les cas limites et les liens vers le contexte. Si vous vous surprenez à écrire un commentaire pour expliquer une ligne déroutante, c'est souvent le signe qu'il faut plutôt renommer une variable ou découper la logique dans une fonction bien nommée.

Suivant : Variables

Maintenant que vous savez annoter votre code, le prochain élément de base est d'y stocker des données. La page suivante traite des variables : comment les déclarer, les types intégrés qu'elles contiennent et les règles que C++ impose parce qu'il est typé statiquement.