c. Les commentaires en Java

Dans le cours précédent nous avons écrit un programme simple pour afficher le message "Hello world !" à l'écran.

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello world !");
    }
}

C'est un programme simple qui se lit facilement, il a quelques lignes. A l'avenir vous aller écrire des centaines voir des milliers de lignes de code, il vous faudra une manière de vous repérer dans le code, c'est là que les commentaires entrent en jeux.

Les commentaires en Java, ce sont des textes que vous écrivez à différents endroits dans votre code. Ces textes ne feront pas partir du programme final, ils seront retirés lors de la compilation. Ces commentaires sont des indications et explications, le but c'est de rendre votre code source lisible et facilement compréhensible par les autres développeurs et vous lorsque vous relisez le code une autre fois.

En Java il y a 3 manières de mettre les commentaires dans votre code :

1 - Les commentaires sur une ligne :

Pour mettre les commentaires sur une ligne, vous commencez la ligne par deux slashes (//) et vous écrivez le commentaire en suite, comme cela :

// ceci est un commentaire sur une ligne

D'habitude ces types de commentaires sont placés :

• - en haut du code au quel on fait référence ou qu'on veut expliquer.
• - ou bien à la fin d'une ligne de code qu'on veut expliquer.

// cette methode est spéciale, c'est le point d'entré de notre programme
public static void main(String[] args) {
    System.out.println("Hello world !"); // c'est une instruction pour afficher le message 'Hello world !' à l'écran.
}

2 - Les commentaires sur plusieurs lignes :

Pour faire de longues explications, sur plusieurs lignes, il faut commencer le texte par /* et puis terminer par */ et c'est bon tout le texte situé entre /* */ sera considéré comme un commentaire. Par exemple :

/*
Ceci est un programme
pour afficher un message à l'écran
en particulier le message 'Hello world !'
*/

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello world !"); /* on peut aussi les utiliser pour des commentaires sur une ligne */
    }
}

3 - Les commentaires pour servir de documentation :

Ces types de commentaires sont utilisés pour générer les documentations. Pour mettre ces types de commentaires il faut commencer par /** et mettre le commentaire qui servira de documentation, pui terminer par */. Par example :

/**
*Ceci est un programme pour afficher un message à l'écran
*@author Grenier du dev Team
*@version 0.1
*/


public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello world !"); /* on peut aussi les utiliser pour des commentaires sur une ligne */
    }
}

Pour générer la documentation, on va utiliser javadoc un programme ou utilitaire, qui a été installé lorsqu'on a installé OpenJDK.

Dans le terminal allez dans le dossier racine(celui qui contient le dossier helloworld) et tapez la commande :

javadoc -d doc helloworld/HelloWorld.java

Ici :

• - doc = le dossier qui va contenir la documentation générée (des fichiers html, css etc..)
• - helloworld/HelloWorld.java = le chemin vers le fichier source.

Pour lire la documentation allez dans le dossier doc, puis ouvrez le fichier index.html dans le navigateur.