Commentaires en Java : sur une ligne, sur plusieurs lignes et Javadoc

À quoi servent les commentaires

Un commentaire est du texte dans votre code source que le compilateur Java ignore complètement. Il ne fait jamais partie du programme en cours d'exécution : 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.

Java possède trois sortes de commentaires : sur une ligne (//), de bloc sur plusieurs lignes (/* */) et de documentation Javadoc (/** */). Ils remplissent tous la même fonction de base — être ignorés à la compilation —, mais vous recourez à chacun dans des situations différentes.

Commentaires sur une ligne

Deux barres obliques (//) entament un commentaire qui s'étend jusqu'à la fin de la ligne courante. Le compilateur ignore tout, du // jusqu'au saut de ligne.

public class Main {
    public static void main(String[] args) {
        // Affiche un message d'accueil dans la console
        System.out.println("Hello, Java!");

        int score = 90; // un commentaire peut aussi se placer après du code
        System.out.println(score);
    }
}

Remarquez que le second commentaire partage sa ligne avec du vrai code. Tout ce qui se trouve 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 sur plusieurs lignes

Lorsque 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é.

public class Main {
    public static void main(String[] args) {
        /*
         * Ce programme montre un commentaire de bloc.
         * Les astérisques au début de chaque ligne ne sont qu'une
         * convention de lisibilité : ils ne sont pas obligatoires.
         */
        System.out.println("Block comments are handy.");
    }
}

Les caractères * alignés le long du bord gauche sont une convention de style, pas une règle. Les seules parties qui comptent réellement sont le /* d'ouverture et le */ de fermeture.

Mettre du code en commentaire

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 d'un coup.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Exécutez-le et vous verrez que seules les deux lignes « runs » s'affichent. Les appels à println mis en commentaire sont invisibles pour le compilateur.

Un piège fréquent : 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 /* ... */ dans un autre bloc /* ... */ : le */ interne met fin à l'ensemble et le reste devient une erreur de syntaxe. Si vous devez désactiver une zone qui contient déjà des commentaires de bloc, utilisez // sur chaque ligne (la plupart des éditeurs le font avec un seul raccourci clavier).

Commentaires de documentation Javadoc

Un commentaire Javadoc ressemble à un commentaire de bloc, mais commence par /** — deux astérisques. Il sert à documenter une classe, une méthode ou un champ, et se place juste au-dessus de l'élément qu'il décrit. L'outil javadoc les transforme en documentation d'API HTML navigable, et les IDE les affichent en infobulle au survol.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

Les balises @param, @return et @throws sont des champs structurés que l'outillage comprend. Pour le compilateur, cela reste un simple commentaire ignoré : sa valeur réside entièrement dans la documentation qu'il produit et dans les indications que l'IDE fournit aux autres développeurs (et à vous-même, six mois plus tard).

Bons commentaires ou bruit

Un commentaire devrait expliquer quelque chose que le code ne peut pas dire de lui-même. Les commentaires qui ne font que répéter ce que fait le code ajoutent du désordre et tendent à se périmer à mesure que le code change.

// Mauvais : répète simplement ce que le code fait de façon évidente
int i = i + 1; // ajoute un à i

// Mieux : explique la raison, que le code ne peut pas montrer
retries++; // patiente puis réessaie ; l'API est limitée à 5 req/s

Efforcez-vous de rendre le code lisible grâce à des noms clairs et une bonne structure, et réservez les commentaires au pourquoi : intention, compromis, cas limites et liens vers le contexte. Si vous vous surprenez à écrire un commentaire pour expliquer une ligne déroutante, c'est souvent le signe qu'il vaut mieux renommer une variable ou extraire une méthode.

Suite : Les variables

Maintenant que vous savez annoter votre code, la prochaine brique de base consiste à y stocker des données. La page suivante traite des variables : comment les déclarer, les types qu'elles contiennent et les règles que Java impose parce qu'il est à typage statique.