Programmation Java/Commentaires

Un livre de Wikilivres.
Aller à : navigation, rechercher

Un commentaire permet d'insérer du texte qui ne sera pas compilé ni interprété. Il sert à ajouter du texte au code source.

Il est utile pour expliquer ce que fait le code source :

  • expliquer le choix technique effectué : pourquoi tel algorithme et pas un autre, pourquoi appeler telle méthode, ...
  • expliquer ce qui devra être fait par la suite (liste de chose à faire) : amélioration, problème à corriger, ...
  • donner les explications nécessaires à la compréhension du code pour le reprendre soi-même plus tard, ou pour d'autres développeurs.

Il peut aussi être utilisé pour que le compilateur ignore une partie du code : code temporaire de déboggage, code en cours de développement, ...

Il est également utile pour la documentation des classes.

Syntaxe[modifier | modifier le wikicode]

Les commentaires en Java utilisent la même syntaxe qu'en C++.

Un commentaire de fin de ligne commence par un double slash et se termine au retour à la ligne.

Exemple :

// Un commentaire pour donner l'exemple
 
int n = 10; // 10 articles

Un commentaire sur plusieurs lignes est encadré par slash + étoile, et étoile + slash.

Exemple:

/*
Ceci est un commentaire
sur plusieurs lignes.
*/
 
/*
Code de déboggage désactivé :
 
int a=10;
while (a-->0) System.out.println("DEBUG: tab["+a+"]="+tab[a]);
*/

Documentation des classes[modifier | modifier le wikicode]

Java permet de documenter les classes et leurs membres en utilisant une syntaxe particulière des commentaires.

Syntaxe[modifier | modifier le wikicode]

Un commentaire de documentation est encadré par slash-étoile-étoile et étoile-slash (soit /** ... */). La documentation est au format HTML.

Exemple :

/**
    Une classe pour donner un <b>exemple</b> de documentation HTML.
*/
public class Exemple {
    /** ...Documentation du membre de type entier nommé exemple... */
    public int exemple;
}

Le commentaire de documentation se place juste avant l'entité commentée (classe, constructeur, méthode, champ).

Dans un commentaire de documentation, la première partie est un texte de description au format HTML. La seconde partie est une liste d'attributs spéciaux dont le nom commence par un arobase ( @ ).

Exemple pour la méthode suivante :

/**
    Obtenir la somme de deux entiers.
    @param a Le premier nombre entier.
    @param b Le deuxième nombre entier.
    @return La valeur de la somme des deux entiers spécifiés.
*/
public int somme(int a, int b) {
    return a + b;
}
Obtenir la somme de deux entiers.
Description de la méthode somme.
@param a Le premier nombre entier.
Attribut de description du paramètre a de la méthode.
@param b Le deuxième nombre entier.
Attribut de description du paramètre b de la méthode.
@return La valeur de la somme des deux entiers spécifiés.
Attribut de description de la valeur retournée par la méthode.

Voici une liste non exhaustive des attributs spéciaux :

Attribut et syntaxe Dans un commentaire de ... Description
@author auteur classe Nom de l'auteur de la classe.
@version version classe Version de la classe.
@deprecated description classe, constructeur, méthode, champ Marquer l'entité comme obsolète (ancienne version), décrire pourquoi et par quoi la remplacer.

Si l'entité marquée comme obsolète par cet attribut est utilisée, le compilateur donne un avertissement.

@see référence classe, constructeur, méthode, champ Ajouter un lien dans la section "Voir aussi".
@param description de l'id constructeur et méthode Décrire un paramètre de méthode.
@return description méthode Décrire la valeur retournée par une méthode.
@exception description du type constructeur et méthode Décrire les raisons de lancement d'une exception du type spécifié (clause throws).

Voir également le chapitre sur les annotations depuis Java 5.

Documentation[modifier | modifier le wikicode]

Le JDK fournit un outil nommé javadoc qui permet de générer la documentation des classes correctement commentées.

La commande javadoc sans argument donne la syntaxe complète de la commande.

Exemple : pour une classe nommée Exemple définie dans un package nommé org.wikibooks.fr dans le fichier C:\ProgJava\org\wikibooks\fr\Exemple.java :

package org.wikibooks.fr;
 
/**
    Une classe d'exemple.
*/
public class Exemple {
    /**
        Obtenir la somme de deux entiers.
        @param a Le premier nombre entier.
        @param b Le deuxième nombre entier.
        @return La valeur de la somme des deux entiers spécifiés.
    */
    public int somme(int a, int b) {
        return a + b;
    }
}

La documentation peut être générée dans un répertoire spécifique (C:\ProgDoc par exemple) avec la commande suivante :

javadoc -locale fr_FR -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.wikibooks.fr

Les options de cette commande sont décrits ci-dessous :

-locale fr_FR
La documentation est en français.
-use
Créer les pages sur l'utilisation des classes et paquetages (packages).
-classpath C:\ProgJava
Le chemin des classes compilées (*.class).
-sourcepath C:\ProgJava
Le chemin des classes sources (*.java).
-d C:\ProgDoc
Le chemin où la documentation doit être générée.
org.wikibooks.fr
Le nom du paquetage (package) à documenter. Il est possible de spécifier plusieurs paquetages, ou un ou plusieurs noms de classe pour ne documenter que celles-ci.

La page de description d'un paquetage copie le texte de description à partir d'un fichier nommé package.html qui doit se situer dans le répertoire correspondant. Dans notre exemple, il faut documenter le paquetage dans le fichier C:\ProgJava\org\wikibooks\fr\package.html.

Dans les versions récentes de Java, le fichier package.html peut être remplacé par un fichier Java spécial nommé package-info.java contenant uniquement la déclaration du paquetage (package) précédée d'un commentaire de documentation.

Exemple (C:\ProgJava\org\wikibooks\fr\package-info.java) :

/**
  Ce paquetage fictif sert à illustrer le livre sur Java
  de <i>fr.wikibooks.org</i>.
*/
package org.wikibooks.fr;