Les commentaires Java

Les commentaires sont des textes que le compilateur ignore. Ils existent pour les personnes qui lisent le code source. Java propose trois types de commentaires — sur une ligne, multi-lignes et Javadoc — chacun ayant son propre rôle.

Ce chapitre couvre la syntaxe des trois styles, comment générer de la documentation HTML à partir de Javadoc, et — tout aussi important — quand un commentaire vaut la peine d'être écrit et quand il n'ajoute que du bruit. Si vous débutez avec la structure de Java, lisez d'abord Java Syntax.

Commentaires sur une ligne — //

Tout ce qui suit // jusqu'à la fin de la ligne est un commentaire :

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

Utilisez-les pour de courtes notes à côté d'une ligne de code, ou pour désactiver temporairement une ligne lors du débogage.

Commentaires multi-lignes — /* ... */

Tout ce qui se trouve entre /* et */ est ignoré, même sur plusieurs lignes :

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

Les commentaires multi-lignes peuvent également apparaître en ligne :

int width = 800 /* pixels */;

Vous ne pouvez pas les imbriquer : /* outer /* inner */ */ se termine au premier */, laissant des caractères */ isolés qui empêchent la compilation. Pour « commenter » un bloc qui contient déjà /* … */, utilisez // sur chaque ligne (votre IDE dispose d'un raccourci pour cela — généralement Ctrl+/ / Cmd+/).

Commentaires Javadoc — /** ... */

Les commentaires Javadoc commencent par /** (notez : deux étoiles) et sont lus par l'outil javadoc pour générer de la documentation HTML :

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Les commentaires Javadoc sont placés immédiatement au-dessus de la classe, de la méthode ou du champ qu'ils décrivent. La première phrase devient la ligne de résumé dans la documentation générée.

Les balises les plus utiles :

• @param name description — une par paramètre
• @return description — ce que la méthode retourne
• @throws ExceptionClass description — quand la méthode lève une exception
• @see ClassOrLink — référence croisée
• @since 1.5 — à partir de quelle version cette API a été ajoutée
• @deprecated reason — déconseille une utilisation supplémentaire (le compilateur avertit également)

L'ensemble de la bibliothèque standard est documenté avec Javadoc ; les IDE le lisent pour alimenter leurs infobulles.

Génération de la documentation HTML

L'outil javadoc est livré avec le JDK. Pointez-le vers vos fichiers sources (ou packages) et il génère un site HTML consultable :

javadoc -d docs Greeter.java

Le drapeau -d docs choisit le répertoire de sortie. Ouvrez docs/index.html dans un navigateur pour voir les pages générées — la même mise en page que vous obtenez sur les docs officielles de l'API Oracle, construite à partir des commentaires au-dessus de chaque classe et méthode.

Quand commenter, quand ne pas commenter

Un bon code se documente lui-même. Les commentaires qui répètent ce que le code montre déjà ne font qu'ajouter du bruit et vieillissent mal :

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

Les commentaires justifient leur place lorsqu'ils expliquent le pourquoi, pas le quoi :

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

Ou lorsqu'ils documentent une contrainte non évidente :

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

Pour les API publiques, écrivez des commentaires Javadoc. Pour le code interne, n'écrivez que les commentaires qui aident le prochain lecteur à prendre une décision.

Une démonstration

Le compilateur supprime les trois styles de commentaires avant de générer le bytecode, donc ils n'ont aucun coût à l'exécution.

Et ensuite

Maintenant que vous pouvez documenter du code, passez aux blocs de construction qu'il décrit :

• Java Variables — déclaration, initialisation et portée.
• Java Syntax — instructions, blocs et règles appliquées par le compilateur.
• Java Hello World — le programme minimal dans lequel vivent vos commentaires.

Pratique