2.4.2 – Commentaires

Les commentaires sont des annotations dans le code qui ne sont pas exécutées par Java. Ils servent à expliquer le code, à documenter les fonctionnalités, et à faciliter la compréhension pour vous-même et pour les autres développeurs. Cette section vous apprendra à utiliser efficacement les commentaires en Java.

💬 Types de commentaires en Java

Java offre trois types de commentaires :

1. Commentaire sur une ligne (//)

Le commentaire sur une ligne commence par // et s'étend jusqu'à la fin de la ligne :

Exemple : Commentaire sur une ligne

int age = 25;  // Âge de l'utilisateur
int x = 10;    // Variable temporaire
// Cette ligne est entièrement un commentaire
System.out.println("Hello");  // Affiche "Hello"

2. Commentaire sur plusieurs lignes (/* */)

Le commentaire sur plusieurs lignes commence par /* et se termine par */ :

Exemple : Commentaire sur plusieurs lignes

/*
 * Ceci est un commentaire
 * qui s'étend sur
 * plusieurs lignes
 */

int x = 10;
/* Ceci est aussi un commentaire
   sur plusieurs lignes */

3. Commentaire de documentation (/** */)

Le commentaire de documentation (JavaDoc) commence par /** et se termine par */. Il est utilisé pour générer automatiquement de la documentation :

Exemple : Commentaire JavaDoc

/**
 * Calcule la somme de deux nombres.
 * 
 * @param a Le premier nombre
 * @param b Le deuxième nombre
 * @return La somme de a et b
 */
public int additionner(int a, int b) {
    return a + b;
}

✅ Quand utiliser les commentaires

1. Expliquer le "pourquoi", pas le "comment"

Les commentaires doivent expliquer pourquoi le code fait quelque chose, pas comment il le fait (le code lui-même devrait être clair) :

Bien :

// Utiliser une multiplication par 2 au lieu d'une addition
// pour éviter les problèmes de précision avec les nombres décimaux
double resultat = nombre * 2;

À éviter :

// Multiplie nombre par 2
double resultat = nombre * 2;  // Le code est déjà clair, pas besoin de commentaire

2. Documenter les fonctions complexes

Exemple : Commenter un algorithme complexe

/**
 * Calcule le plus grand commun diviseur (PGCD) de deux nombres
 * en utilisant l'algorithme d'Euclide.
 * 
 * @param a Premier nombre
 * @param b Deuxième nombre
 * @return Le PGCD de a et b
 */
public int pgcd(int a, int b) {
    // Algorithme d'Euclide : on remplace a par b et b par a % b
    // jusqu'à ce que b soit égal à 0
    while (b != 0) {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}

3. Expliquer les décisions de conception

Exemple : Expliquer une décision

// Utiliser ArrayList au lieu de tableau fixe
// car la taille de la liste peut varier dynamiquement
List noms = new ArrayList<>();

4. Marquer du code temporaire ou à améliorer

Exemple : Code temporaire

// TODO : Optimiser cet algorithme pour les grandes listes
// FIXME : Gérer le cas où la liste est vide
// HACK : Solution temporaire, à refactorer plus tard

❌ Quand ne PAS utiliser de commentaires

1. Ne pas commenter l'évident

À éviter :

int age = 25;  // Déclare une variable age et lui assigne 25
String nom = "Jean";  // Déclare une variable nom et lui assigne "Jean"
System.out.println("Hello");  // Affiche "Hello"

2. Ne pas utiliser de commentaires pour masquer du mauvais code

Si vous avez besoin de beaucoup de commentaires pour expliquer votre code, c'est peut-être que le code lui-même devrait être amélioré :

Mieux vaut améliorer le code :

// Au lieu de :
// Calcule le prix avec la réduction de 10% si le client est premium
double prixFinal = prix * 0.9;

// Écrivez :
double prixFinal = calculerPrixAvecReduction(prix, estClientPremium);

📝 Bonnes pratiques pour les commentaires

• Être concis : Les commentaires doivent être courts et pertinents
• Rester à jour : Mettez à jour les commentaires quand vous modifiez le code
• Utiliser JavaDoc : Pour documenter les classes et méthodes publiques
• Éviter les commentaires redondants : Ne répétez pas ce que le code dit déjà
• Utiliser un langage clair : Écrivez en français (ou dans la langue de votre équipe)
• Formater proprement : Alignez les commentaires pour la lisibilité

📚 JavaDoc : Documentation automatique

JavaDoc est un outil qui génère automatiquement de la documentation HTML à partir de commentaires spéciaux. C'est la norme pour documenter les API Java :

Exemple complet de JavaDoc :

/**
 * Représente une personne avec un nom et un âge.
 * 
 * @author Jean Dupont
 * @version 1.0
 * @since 2024
 */
public class Personne {
    private String nom;
    private int age;
    
    /**
     * Constructeur qui crée une nouvelle personne.
     * 
     * @param nom Le nom de la personne
     * @param age L'âge de la personne (doit être positif)
     */
    public Personne(String nom, int age) {
        this.nom = nom;
        this.age = age;
    }
    
    /**
     * Retourne le nom de la personne.
     * 
     * @return Le nom de la personne
     */
    public String getNom() {
        return nom;
    }
    
    /**
     * Calcule l'âge dans 10 ans.
     * 
     * @return L'âge de la personne dans 10 ans
     */
    public int ageDans10Ans() {
        return age + 10;
    }
}

💡 Points clés à retenir

• Commentaire ligne : // pour un commentaire sur une ligne
• Commentaire bloc : /* */ pour un commentaire sur plusieurs lignes
• JavaDoc : /** */ pour la documentation automatique
• Expliquer le "pourquoi" : Pas le "comment" (le code doit être clair)
• Documenter les fonctions : Utilisez JavaDoc pour les méthodes publiques
• Rester à jour : Mettez à jour les commentaires avec le code
• Éviter l'évident : Ne commentez pas ce qui est déjà clair