Programmation Java/Commentaires
Un livre de Wikibooks.
| Programmation |
| Java |
 |
| Sommaire |
| IHM avec SWING |
| Annexes |
| Modifier ce modèle |
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.
Sections |
[modifier] Syntaxe
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]); */
[modifier] Documentation des classes
Java permet de documenter les classes et leurs membres en utilisant une syntaxe particulière des commentaires.
[modifier] Syntaxe
Un commentaire de documentation est encadré par slash-étoile-étoile et étoile-slash. 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 author | 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 reference | classe, constructeur, méthode, champ | Ajouter un lien dans la section "Voir aussi". |
| @param id description | 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 type description | constructeur et méthode | Décrire les raisons de lancement d'une exception du type spécifié (clause throws). |
[modifier] Documentation
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.
