Les commentaires en Rust

Les commentaires sont des notes que vous laissez dans votre code pour les humains qui le liront. Rust les ignore complètement à la compilation : ils ne changent jamais le comportement de votre programme. Un bon commentaire explique pourquoi le code fait quelque chose, pas seulement ce qu’il fait.

Les commentaires de ligne

Le commentaire le plus courant commence par //. Tout ce qui suit // sur la ligne est ignoré :

fn main() {
    // Ceci est un commentaire : Rust l'ignore complètement
    println!("Bonjour !"); // un commentaire peut aussi se placer en fin de ligne
}

Sortie :

Bonjour !

▶ Essayez par vous-même

Les commentaires sur plusieurs lignes

Pour une note plus longue, vous pouvez commencer chaque ligne par // :

fn main() {
    // Ce programme salue l'utilisateur.
    // Il affiche une seule ligne de texte.
    // Écrit comme premier exemple.
    println!("Bonjour !");
}

Sortie :

Bonjour !

▶ Essayez par vous-même

Rust accepte aussi les commentaires de bloc, entre /* et */, qui peuvent s’étendre sur plusieurs lignes :

fn main() {
    /*
      Ceci est un commentaire de bloc.
      Il peut couvrir plusieurs lignes
      sans // au début de chacune.
    */
    println!("Bonjour !");
}

Sortie :

Bonjour !

▶ Essayez par vous-même

En pratique, la plupart du code Rust utilise // même sur plusieurs lignes : c’est l’usage dans la communauté, et cela fonctionne bien avec les raccourcis des éditeurs.

Mettre du code en commentaire

Les commentaires sont pratiques pour désactiver temporairement une ligne pendant que vous testez quelque chose :

fn main() {
    println!("Ceci s'exécute");
    // println!("Ceci est désactivé pour l'instant");
}

Sortie :

Ceci s'exécute

▶ Essayez par vous-même

Écrire des commentaires utiles

Un commentaire qui répète le code n’apporte rien. Le code dit déjà ce qui se passe. Un bon commentaire dit pourquoi, ou prévient d’un piège que le lecteur ne peut pas voir :

fn main() {
    let minutes = 135;

    // Le minuteur n'affiche que des heures entières. La division entière
    // supprime le reste, et c'est exactement ce qu'on veut ici.
    let hours = minutes / 60;
    let leftover = minutes - hours * 60; // les minutes qui ne font pas une heure complète

    println!("{hours} h {leftover} min");
}

Sortie :

2 h 15 min

▶ Essayez par vous-même

Comparez avec un commentaire comme // divise minutes par 60. C’est vrai, mais tout le monde sait lire minutes / 60. L’information utile, c’est pourquoi la division convient ici.

Quelques autres bonnes habitudes à prendre :

Gardez vos commentaires à jour. Un commentaire qui ne correspond plus au code est pire que pas de commentaire du tout, parce que les gens lui font confiance.
// TODO: est une façon courante de signaler un travail inachevé, par exemple // TODO: gérer les nombres négatifs. Beaucoup d’éditeurs le mettent en évidence et peuvent lister tous les TODO d’un projet.
Les commentaires de bloc s’imbriquent en Rust. Contrairement au C, vous pouvez entourer d’un commentaire du code qui contient déjà un commentaire /* */, et cela fonctionne quand même :

fn main() {
    /* Désactivé pour l'instant :
       println!("ancien message"); /* disait bonjour à tout le monde */
    */
    println!("nouveau message");
}

Sortie :

nouveau message

▶ Essayez par vous-même

Les commentaires de documentation

Rust a un type de commentaire spécial qui commence par /// (trois barres obliques). Ce sont les commentaires de documentation (doc comments) : ils décrivent les fonctions, et Rust peut les transformer en site de documentation navigable avec cargo doc.

/// Additionne deux nombres et renvoie le résultat.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Vous n’avez pas encore besoin des commentaires de documentation en tant que débutant. Retenez simplement que /// sert à la documentation, tandis que // sert aux notes ordinaires. Quand vous serez prêt, la page Documentation vous montrera comment les écrire, générer la documentation et même transformer vos exemples en tests.

Exercices

1. Désactiver une ligne

Ce programme affiche trois lignes. Transformez la ligne du milieu en commentaire pour que seules Ligne 1 et Ligne 3 s’affichent. Indice : placez // au début de la ligne à désactiver.

fn main() {
    println!("Ligne 1");
    println!("Ligne 2");
    println!("Ligne 3");
}

Voir la solution

fn main() {
    println!("Ligne 1");
    // println!("Ligne 2");
    println!("Ligne 3");
}

Sortie :

Ligne 1
Ligne 3

▶ Essayez par vous-même

2. Désactiver deux lignes d’un coup

Affichez maintenant Ligne 1 à Ligne 4, mais utilisez un seul commentaire de bloc pour désactiver les lignes 2 et 3. Indice : ouvrez le commentaire avec /* avant la ligne 2 et fermez-le avec */ après la ligne 3.

Voir la solution

fn main() {
    println!("Ligne 1");
    /*
    println!("Ligne 2");
    println!("Ligne 3");
    */
    println!("Ligne 4");
}

Sortie :

Ligne 1
Ligne 4

▶ Essayez par vous-même

Récapitulatif

Les commentaires sont des notes que Rust ignore ; utilisez-les pour expliquer votre code.
// commence un commentaire de ligne (le plus courant).
/* ... */ est un commentaire de bloc pour plusieurs lignes, et les commentaires de bloc peuvent s’imbriquer.
Un bon commentaire explique pourquoi, pas ce que le code dit déjà.
/// est un commentaire de documentation, utilisé pour générer la documentation.

Petit quiz

1. Que fait Rust des commentaires quand il compile votre code ?

2. À quoi servent les commentaires /// ?

Score : 0 / 2

Pour aller plus loin

Comments — The Rust Book (en anglais) : la courte section officielle sur les commentaires // et l’endroit où on les place en général.
Comments — Rust by Example (en anglais) : tous les styles de commentaires dans un seul exemple exécutable, y compris des commentaires de bloc au milieu d’une expression.
Making Useful Documentation Comments — The Rust Book (en anglais) : un premier aperçu de /// et //!, et de la façon dont cargo doc les utilise.
How to write documentation — The rustdoc book (en anglais) : des conseils sur le contenu d’un bon commentaire de documentation, pour quand vous écrirez une bibliothèque.
Comments — The Rust Reference (en anglais) : les règles exactes, y compris pour les commentaires de bloc imbriqués.