Les commentaires dans le code Java : pourquoi et comment les utiliser

Quand on écrit du code, les commentaires jouent un rôle essentiel, même s’ils sont parfois sous-estimés.

En Java, un commentaire est un morceau de code ignoré par le compilateur, qui permet d’ajouter des explications ou des notes dans le code source.

Pourquoi commenter son code ?

Les commentaires aident à rendre le code plus compréhensible pour soi-même et pour les autres développeurs qui pourront travailler dessus plus tard.

Ils permettent :

• D’expliquer la logique ou l’objectif d’un bout de code.
• De préciser les entrées, sorties ou effets d’une méthode.
• D’annoter des points techniques ou des décisions importantes.
• De signaler les améliorations à faire ou les bugs connus.
• De garder une trace des idées ou alternatives envisagées.

Un code bien commenté est plus facile à maintenir et à relire par ses pairs.

Les types de commentaires en Java

Java offre trois principaux types de commentaires :

1. Commentaires sur une seule ligne

Commencent par // et vont jusqu’à la fin de la ligne. Ce sont les plus courants :

// Ceci est un commentaire sur une seule ligne
int a = 5; // initialisation de la variable a

2. Commentaires multi-lignes (ou en bloc)

Délimités par /* au début et */ à la fin. Ils peuvent couvrir plusieurs lignes :

/*
 * Ceci est un commentaire
 * qui s’étend sur plusieurs lignes
 */
int b = 10;

3. Commentaires de documentation (JavaDoc)

Similaires aux commentaires multi-lignes, ils commencent par /** et terminent par */.

Ces commentaires sont destinés à la génération automatique de documentation pour les classes et méthodes.

Ils peuvent inclure des tags comme @param, @return, ou @author.

/**
 * Calcule la somme de deux nombres.
 *
 * @param x premier nombre
 * @param y second nombre
 * @return la somme de x et y
 */
public int addition(int x, int y) {
return x + y;
}

🚧 Attention aux fermetures de commentaire qui se chevauchent

Par exemple ce code renvoie une erreur lors de la compilation :

/*
 * Je suis un commentaire multi-lignes
 * /* moi aussi */
 */

Malgré que les IDEs permettent d'identifier les problèmes dans son code, il est important de garder ça en tête.

Bonnes pratiques

• Commente ce qui n’est pas évident dans le code.
• Ne commente pas l’évidence ou un code simple qui se lit bien.
• Mets à jour les commentaires en même temps que le code.
• Utilise JavaDoc pour documenter les API publiques.
• Sois clair et concis dans tes commentaires.

En résumé, les commentaires sont un outil précieux qui améliore la qualité et la maintenabilité de votre code Java. Bien utilisés, ils font gagner du temps à tout le monde et facilitent grandement la collaboration.

N'hésite pas à commenter intelligemment pour écrire un code plus compréhensible et professionnel !