Commentaires sur Java

En Java, les commentaires sont des déclarations non exécutables qui fournissent des explications ou des annotations dans le code. Ils sont utilisés pour améliorer la lisibilité du code et aider les développeurs à comprendre l'objectif et la fonctionnalité du code. Les commentaires sont ignorés par le compilateur Java pendant l'exécution.

Types de commentaires

Java prend en charge trois types de commentaires :

1. Commentaires sur une seule ligne
2. Commentaires sur plusieurs lignes
3. Documentation Commentaires

Commentaires sur une seule ligne

Les commentaires sur une seule ligne commencent par // et se poursuivent jusqu'à la fin de la ligne. Ils sont utilisés pour de brèves explications ou notes dans le code.

Syntax

 // This is a single-line comment
int number = 10; // This initializes the variable

Commentaires sur plusieurs lignes

Les commentaires sur plusieurs lignes, également appelés commentaires en bloc, commencent par /* et se terminent par */. Ils sont utiles pour commenter plusieurs lignes de code ou fournir des explications détaillées.

Syntax

 /*
This is a multi-line comment.
It can span multiple lines.
*/
int number = 20;

Documentation Commentaires

Les commentaires de documentation, ou commentaires Javadoc, sont des commentaires spéciaux utilisés pour générer la documentation de l'API. Ils commencent par /** et se terminent par */. Ces commentaires sont généralement placés avant les déclarations de classes, de méthodes ou de champs afin de décrire leur objectif et leur utilisation.

Syntax

 /**
 * This is a documentation comment.
 * @param args Command line arguments
 */
public static void main(String[] args) {
    // Code goes here
}

Exemples

Exemple 1 : Utilisation de commentaires sur une seule ligne

 public class SingleLineCommentExample {
    public static void main(String[] args) {
        // Print a message to the console
        System.out.println("Hello, World!"); // Output message
    }
}

Exemple 2 : Utilisation de commentaires sur plusieurs lignes

 public class MultiLineCommentExample {
    public static void main(String[] args) {
        /*
         * This block of code prints a message
         * to the console.
         */
        System.out.println("Hello, Java!");
    }
}

Exemple 3 : Utilisation des commentaires de la documentation

 /**
 * The Calculator class provides basic arithmetic operations.
 */
public class Calculator {
    /**
     * Adds two integers.
     * @param a First integer
     * @param b Second integer
     * @return Sum of a and b
     */
    public int add(int a, int b) {
        return a + b;
    }
}

Tags Javadoc

Les commentaires Javadoc peuvent inclure des balises spécifiques pour fournir des informations supplémentaires sur les éléments de code qu'ils décrivent. Les étiquettes les plus couramment utilisées sont les suivantes :

• @param: Décrit un paramètre de méthode.
• @return: Décrit la valeur de retour d'une méthode.
• @throws ou @exception: Documente une exception levée par une méthode.

Conseils et bonnes pratiques

• Clarté: Utilisez des commentaires pour clarifier la logique d'un code complexe, mais évitez d'énoncer des évidences.
• Cohérence: Maintenir un style cohérent pour les commentaires dans l'ensemble de la base de code.
• Mise à jour des commentaires: Veillez à ce que les commentaires soient mis à jour lorsque le code est modifié afin d'éviter les divergences.
• Évitez les commentaires excessifs: N'abusez pas des commentaires ; le code doit être explicite dans la mesure du possible.
• Javadoc: Utilisez les commentaires Javadoc pour les API publiques afin de faciliter la génération automatique de la documentation.