Les commentaires permettent de rendre votre code lisible et surtout d'en faciliter ultérieurement la maintenance.
En général, l'insertion de commentaire se fait soit en fin de ligne, soit sur une nouvelle ligne mais en aucun cas au sein d'une ligne de commande.
Il existe deux méthodes permettant d'intégrer des commentaires aux programmes Java.
La première consiste à placer un double slash (//) devant le texte comme dans l'exemple ci-dessous :
image = "fond.gif"; //image de fond
if (x = 2) //redirection vers la seconde page
{
url = ("page2.html");
}
else
{ //sinon retourne à la page d'accueil
url = ("accueil.html");
}La seconde solution est d'encadrer le texte par un slash suivi d'une étoile (/*) et la même séquence inversée (*/) comme le montre l'exemple suivant :
/*Voici un commentaire*/
/*
Encore un autre commentaire
*/
/*Ce commentaire est
écrit sur deux lignes*/
Les programmes Java acceptent également des commentaires de documentation visualisables par des navigateurs Web.
Ces commentaires peuvent contenir du balisage HTML, ainsi que des balises spéciales commençant par une arobasce (@) permettant de documenter un programme Java sous une forme standard.
/**
* <p>Titre : Programme Java</p>
* <p>Description : Mon premier programme...</p>
* <p>Copyright : Copyright (c) 2002</p>
* <p>Société : Ma société</p>
* @author Marc MOLARDI
* @version 1.0
*/
Ce genre de commentaire permet de créer une documentation HTML à partir du fichier source (fichier.java)en utilisant l'utilitaire javadoc.exe du kit de développement Java.
Les balises Javadocjavadoc -d c:\chemin\doc\ fichier_source.java
| Balise | Version JDK |
|---|---|
| Description | |
| @author nom prénom | 1.0 |
| désigne le nom de l'auteur. | |
| @deprecated description | 1.0 |
| ajoute un commentaire spécifiant la dépréciation du programme. | |
| @exception nom_classe description | 1.0 |
| indique les exceptions susceptibles de se lancer lors du programme. | |
| {@link ancre} | 1.2 |
| insère un lien interne qui pointe vers une ancre du document en cours. | |
| @param nom description | 1.0 |
| ajoute une description de paramètre à la section "Parameters". | |
| @return description | 1.0 |
| fournit une description dans la rubrique "Returns" à propos du type retourné et de l'intervalle de valeur permis. | |
| @see référence | 1.0 |
| ajoute des références documentaires à consulter dans un rubrique "See Also". | |
| @serial description | 1.2 |
| explique la signification d'un champ dit serializable et la liste de ses valeurs autorisées. | |
| @serialData description | 1.2 |
| fournit une description des séquences et types de données. | |
| @serialField nom_champ type description | 1.2 |
| permet de documenter un composant ObjectStreamField. | |
| @since texte | 1.1 |
| spécifie qu'une caractéristique du programme existe depuis une certaine version du logiciel. | |
| @throws nom_classe description | 1.2 |
| indique les exceptions susceptibles de se lancer lors du programme. | |
| @version texte | 1.0 |
| spécifie le numéro de version du programme. | |