Penser en Java

Il est utile de visualiser certains aspects de comment les choses sont arrangées lorsque le programme tourne, en particulier comment la mémoire est organisée. Il y a six endroits différents pour stocker les données :

1. Les registres. C'est le stockage le plus rapide, car il se trouve à un endroit différent des autres zones de stockage : dans le processeur. Toutefois, le nombre de registres est sévèrement limité, donc les registres sont alloués par le compilateur en fonction de ses besoins. On n'a aucun contrôle direct et il n'y a même aucune trace de l'existence des registres dans les programmes.
2. La pile. Elle se trouve dans la RAM (random access memory), mais elle est prise en compte directement par le processeur via son pointeur de pile. Le pointeur de pile est déplacé vers le bas pour créer plus d'espace mémoire et déplacé vers le haut pour libérer cet espace. C'est un moyen extrêmement efficace et rapide d'allouer de la mémoire, supplanté seulement par les registres. Le compilateur Java doit connaître, lorsqu'il crée le programme, la taille et la durée de vie exacte de toutes les données qui sont rangées sur la pile, parce qu'il doit générer le code pour déplacer le pointeur de pile vers le haut et vers le bas. Cette contrainte met des limites à la flexibilité des programmes, donc bien qu'il y ait du stockage Java sur la pile - en particulier les références aux objets - les objets Java eux-mêmes ne sont pas placés sur la pile.
3. Le segment. C'est une réserve de mémoire d'usage général (aussi en RAM) où résident tous les objets Java. La bonne chose à propos du segment est que, contrairement à la pile, le compilateur n'a pas besoin de savoir combien de place il a besoin d'allouer sur le segment ni combien de temps cette place doit rester sur le segment. Ainsi, il y a une grande flexibilité à utiliser la mémoire sur le segment. Lorsqu'on a besoin de créer un objet, il suffit d'écrire le code pour le créer en utilisant new et la mémoire est allouée sur le segment lorsque le programme s'exécute. Bien entendu il y a un prix à payer pour cette flexibilité : il faut plus de temps pour allouer de la mémoire sur le segment qu'il n'en faut pour allouer de la mémoire sur la pile (c'est-à-dire si on avait la possibilité de créer des objets sur la pile en Java, comme on peut le faire en C++).
4. La mémoire statique. « Statique » est utilisé ici dans le sens « à un endroit fixe » (bien que ce soit aussi dans la RAM). La mémoire statique contient les données qui sont disponibles pendant tout le temps d'exécution du programme. On peut utiliser le mot-clef static pour spécifier qu'un élément particulier d'un objet est statique, mais les objets Java par eux-mêmes ne sont jamais placés dans la mémoire statique.
5. Les constantes. Les valeurs des constantes sont souvent placées directement dans le code du programme, ce qui est sûr puisqu'elles ne peuvent jamais changer. Parfois les constantes sont isolées de façon à pouvoir être optionnellement placées dans une mémoire accessible en lecture seulement (ROM).
6. Stockage hors RAM. Si les données résident entièrement hors du programme, elles peuvent exister même quand le programme ne tourne pas, en dehors du contrôle du programme. Les deux exemples de base sont les flots de données, pour lesquels les données sont transformées en flots d'octets, généralement pour être transmises vers une autre machine, et les objets persistants, pour lesquels les objets sont placés sur disque de façon à ce qu'ils conservent leur état même après que le programme soit terminé. L'astuce avec ces types de stockage est de transformer les objets en quelque chose qui peut exister sur l'autre support, tout en pouvant être ressuscité en un objet normal en mémoire, lorsque c'est nécessaire. Java fournit des outils pour la persistance légère, et les versions futures pourraient fournir des solutions plus complètes pour la persistance.

Il y a un ensemble de types qui sont soumis à un traitement particulier ; ils peuvent être considérés comme les types « primitifs » fréquemment utilisés en programmation. La raison de ce traitement particulier est que la création d'un objet avec new - en particulier une simple variable - n'est pas très efficace parce que new place les objets sur le segment. Pour ces types, Java a recours à l'approche retenue en C et en C++. Au lieu de créer la variable en utilisant new, une variable « automatique », qui n'est pas une référence, est créée. La variable contient la valeur et elle est placée sur la pile, ce qui est beaucoup plus efficace.

Java fixe la taille de chacun des types primitifs. Ces tailles ne changent pas d'une architecture de machine à une autre, comme c'est le cas dans la plupart des langages. L'invariance de la taille de ces types est l'une des raisons pour lesquelles Java est si portable.

Tous les types numériques sont signés, il est donc inutile d'aller chercher après des types non signés.

Les types de données primitifs sont aussi associés à des classes« wrapper ». Ceci signifie que pour faire un objet non primitif sur le segment pour représenter ce type primitif il faut utiliser le wrapper associé. Par exemple :

char c = 'x';Character C = 
new Character(c);

On peut aussi utiliser :

Character C = new 
Character('x');

Les raisons pour lesquelles on fait ceci seront indiquées dans un prochain chapitre.

IV-B-2-a. Nombres de grande précision▲

Pratiquement tous les langages de programmation gèrent les tableaux. Utiliser des tableaux en C ou C++ est dangereux, car ces tableaux ne sont que des blocs de mémoire. Si un programme accède à un tableau en dehors de son bloc mémoire, ou s'il utilise la mémoire avant initialisation (erreurs de programmation fréquentes) les résultats seront imprévisibles.

Un des principaux objectifs de Java est la sécurité, aussi, un grand nombre des problèmes dont souffrent C et C++ ne sont pas répétés en Java. On est assuré qu'un tableau Java est initialisé et qu'il ne peut pas être accédé en dehors de ses bornes. La vérification des bornes se fait au prix d'un petit excédent de mémoire pour chaque tableau ainsi que de la vérification de l'index lors de l'exécution, mais on suppose que le gain en sécurité et en productivité vaut la dépense.

Quand on crée un tableau d'objets, on crée en réalité un tableau de références, et chacune de ces références est automatiquement initialisée à une valeur particulière avec son propre mot-clé : null. Quand Java voit null, il reconnaît que la référence en question ne pointe pas vers un objet. Il faut affecter un objet à chaque référence avant de l'utiliser et si on essaye d'utiliser une référence encore à null, le problème sera signalé lors de l'exécution. Ainsi, les erreurs typiques sur les tableaux sont évitées en Java.

On peut aussi créer des tableaux de variables de type primitif. À nouveau, le compilateur garantit l'initialisation, car il met à zéro la mémoire utilisée par ces tableaux.

Les tableaux seront traités plus en détail dans d'autres chapitres.

La plupart des langages procéduraux ont le concept de portée. Il fixe simultanément la visibilité et la durée de vie des noms définis dans cette portée. En C, C++ et Java, la portée est fixée par l'emplacement des accolades {}. Ainsi, par exemple :

{
int x = 12;
/* seul x est accessible */
{
int q = 96;
/* x & q sont tous les deux accessibles */
}
/* seul x est accessible */
/* q est « hors de portée » */
}

Une variable définie dans une portée n'est accessible que jusqu'à la fin de cette portée.

L'indentation rend le code Java plus facile à lire. Étant donné que Java est un langage indépendant de la mise en page, les espaces, tabulations et retours chariots supplémentaires ne changent pas le programme.

Il faut remarquer qu'on ne peut pas faire la chose suivante, bien que cela soit autorisé en C et C++ :

{
int x = 12;
{
int x = 96; /* illegal */
}
}

Le compilateur annoncera que la variable x a déjà été définie. Ainsi, la faculté du C et du C++ à « cacher » une variable d'une portée plus étendue n'est pas autorisée parce que les concepteurs de Java ont pensé que ceci mène à des programmes confus.

Les objets Java n'ont pas la même durée de vie que les variables primitives. Quand on crée un objet Java avec new, il existe toujours après la fin de la portée. Ainsi, si on fait :

{
String s = new String("a string");
} /* fin de portée */

la référence s disparaît à la fin de la portée. Par contre l'objet String sur lequel s pointait occupe toujours la mémoire. Dans ce bout de code, il n'y a aucun moyen d'accéder à l'objet parce que son unique référence est hors de portée. Dans d'autres chapitres, on verra comment la référence à un objet peut être transmise et dupliquée dans un programme.

Il s'avère que du simple fait qu'un objet créé avec new reste disponible tant qu'on le veut, tout un tas de problèmes de programmation du C++ disparaissent tout simplement en Java. Il semble que les problèmes les plus durs surviennent en C++ parce que le langage ne fournit aucune aide pour s'assurer que les objets sont disponibles quand on en a besoin. Et, encore plus important, en C++ on doit s'assurer qu'on détruit bien les objets quand on en a terminé avec eux.

Ceci amène une question intéressante. Si Java laisse les objets traîner, qu'est-ce qui les empêche de complètement remplir la mémoire et d'arrêter le programme ? C'est exactement le problème qui surviendrait dans un programme C++. C'est là qu'un peu de magie apparaît. Java a un ramasse-miettes qui surveille tous les objets qui ont été créés avec new et qui arrive à deviner lesquels ne sont plus référencés. Ensuite, il libère la mémoire de ces objets de façon à ce que cette mémoire puisse être utilisée pour de nouveaux objets. Ceci signifie qu'il ne faut jamais s'embêter à récupérer la mémoire soi-même. On crée simplement les objets, et quand on n'en a plus besoin, ils disparaissent d'eux-mêmes. Ceci élimine toute une classe de problèmes de programmation : les soi-disant « fuites de mémoire » qui arrivent quand un programmeur oublie de libérer la mémoire.

IV-C-2-a. Valeurs par défaut des membres primitifs▲

int x;

La liste de paramètres de la méthode spécifie quelles informations on passe à la méthode. Comme on peut le supposer, ces informations -- comme tout le reste en Java -- sont sous la forme d'objets. On doit donc indiquer dans la liste de paramètres les types des objets à transmettre et les noms à employer pour chacun. Comme dans toutes les situations où on a l'impression de manipuler des objets, en Java on passe effectivement des références name="fnB23">(17). Toutefois, le type de la référence doit être correct. Si le paramètre est censé être un objet de type String, ce qu'on transmet doit être de ce type.

Considérons une méthode qui prend un objet de classe String en paramètre. Voici la définition qui doit être mise à l'intérieur de la définition d'une classe pour qu'elle soit compilée :

int storage(String s) {
return s.length() * 2;
}

Cette méthode indique combien d'octets sont nécessaires pour contenir une String donnée (chaque char dans une String fait 16 bits, ou deux octets, pour permettre les caractères Unicode). Le paramètre est de type String et il est appelé s. Une fois que s est passé à une méthode, il peut être traité comme n'importe quel autre objet (on peut lui envoyer des messages). Ici, on appelle la méthode length( ) qui est une des méthodes de la classe String ; elle retourne le nombre de caractères que contient la chaîne.

On peut aussi voir l'utilisation du mot-clef return qui fait deux choses. D'abord, il signifie « quitte la méthode, j'ai terminé ». Ensuite, si la méthode retourne une valeur, cette valeur est placée juste après la déclaration du return. Dans le cas présent, la valeur de retour est produite en évaluant l'expression s.length( ) * 2.

On peut retourner des valeurs de tous les types qu'on souhaite, mais si on souhaite ne rien retourner du tout on peut le faire en indiquant que la méthode retourne void. Voici quelques exemples :

boolean flag() { return true; }
float naturalLogBase() { return 2.718f; }
void nothing() { return; }
void nothing2() {}

Quand le type de retour est void, alors le mot-clef return n'est utilisé que pour sortir de la méthode, il n'est donc pas nécessaire quand on atteint la fin de la méthode. On peut retourner d'une méthode à n'importe quel endroit, mais si on a indiqué un type de retour qui n'est pas void alors le compilateur imposera (avec des messages d'erreur) un retour avec une valeur d'un type approprié sans tenir compte de l'endroit auquel le retour se produit.

À ce point, on peut penser qu'un programme n'est qu'un paquet d'objets avec des méthodes qui prennent d'autres objets en paramètres pour transmettre des messages à ces autres objets. C'est effectivement l'essentiel de ce qui se passe, mais dans les chapitres suivants on verra comment faire le travail de bas niveau en prenant des décisions au sein d'une méthode. Pour ce chapitre, envoyer des messages est suffisant.

Un problème commun à tous les langages de programmation est le contrôle des noms. Si on utilise un nom dans un module du programme et si un autre programmeur utilise le même nom dans un autre module, comment distingue-t-on un nom d'un autre et comment empêche-t-on les « collisions » de noms ? En C c'est un problème particulier, car un programme est souvent un océan de noms incontrôlable. Les classes C++ (sur lesquelles les classes Java sont basées) imbriquent les fonctions dans les classes de telle sorte qu'elles ne peuvent pas entrer en collision avec les noms de fonctions imbriqués dans d'autres classes. Toutefois, C++ autorise toujours les données et les fonctions globales, donc les collisions sont toujours possibles. Pour résoudre ce problème, C++ a introduit les domaines de noms (namespace) en utilisant des mots-clefs supplémentaires.

Java a pu éviter tout cela en employant une approche originale. Pour générer sans ambiguïté un nom pour une bibliothèque, le spécificateur utilisé n'est pas très différent d'un nom de domaine Internet. En fait, les créateurs de Java veulent qu'on utilise son propre nom de domaine Internet inversé, puisqu'on est assuré que ceux-ci sont uniques. Puisque mon nom de domaine est BruceEckel.com, ma bibliothèque d'utilitaires (utility) pour mes marottes (foibles) devrait être appelée com.bruceeckel.utility.foibles. Après avoir inversé le nom de domaine, les points sont destinés à représenter des sous-répertoires.

Dans Java 1.0 et Java 1.1 les extensions de domaines com, edu, org, net, etc. étaient mises en lettres capitales par convention, ainsi la bibliothèque serait :COM.bruceeckel.utility.foibles. Toutefois, au cours du développement de Java 2, on s'est rendu compte que cela causait des problèmes et par conséquent les noms de packages sont entièrement en lettres minuscules.

Ce mécanisme signifie que tous les fichiers existent automatiquement dans leur propre domaine de nom et toutes les classes contenues dans un fichier donné doivent avoir un identificateur unique. Ainsi, on n'a pas besoin d'apprendre de particularités spécifiques au langage pour résoudre ce problème - le langage s'en occupe à votre place.

Lorsqu'on souhaite utiliser une classe prédéfinie dans un programme, le compilateur doit savoir comment la localiser. Bien entendu, la classe pourrait déjà exister dans le même fichier source que celui d'où elle est appelée. Dans ce cas on utilise simplement la classe - même si la classe n'est définie que plus tard dans le fichier. Java élimine le problème des « références anticipées », il n'y a donc pas à s'en préoccuper.

Qu'en est-il des classes qui existent dans un autre fichier ? On pourrait penser que le compilateur devrait être suffisamment intelligent pour aller simplement la chercher lui-même, mais il y a un problème. Imaginons que l'on veuille utiliser une classe ayant un nom spécifique, mais qu'il existe plus d'une classe ayant cette définition (il s'agit probablement de définitions différentes). Ou pire, imaginons que l'on écrive un programme et qu'en le créant on ajoute à sa bibliothèque une nouvelle classe qui entre en conflit avec le nom d'une classe déjà existante.

Pour résoudre ce problème, il faut éliminer les ambiguïtés potentielles. Ceci est réalisé en disant exactement au compilateur Java quelles classes on souhaite, en utilisant le mot-clef import. import dit au compilateur d'introduire un package qui est une bibliothèque de classes (dans d'autres langages, une bibliothèque pourrait comporter des fonctions et des données au même titre que des classes, mais il faut se rappeler que tout le code Java doit être écrit dans des classes).

La plupart du temps, on utilise des composantes des bibliothèques Java standard qui sont fournies avec le compilateur. Avec celles-ci il n'y a pas à se tracasser à propos des longs noms de domaines inversés ; il suffit de dire, par exemple :

import java.util.ArrayList;

pour dire au compilateur que l'on veut utiliser la classe JavaArrayList. Toutefois, util contient de nombreuses classes et on pourrait vouloir utiliser plusieurs d'entre elles sans les déclarer explicitement. Ceci est facilement réalisé en utilisant '*' pour indiquer un joker :

import java.util.*;

Il est plus courant d'importer une collection de classes de cette manière que d'importer les classes individuellement.

Normalement, quand on crée une classe, on décrit ce à quoi ressemblent les objets de cette classe et comment ils se comportent. Rien n'existe réellement avant de créer un objet de cette classe avec new ; à ce moment la zone de données est créée et les méthodes deviennent disponibles.

Mais il y a deux situations pour lesquelles cette approche n'est pas suffisante. L'une, si on veut avoir une zone de stockage pour des données spécifiques, sans tenir compte du nombre d'objets créés, ou même si aucun objet n'a été créé. L'autre, si on a besoin d'une méthode qui n'est associée à aucun objet particulier de la classe. C'est-à-dire si on a besoin d'une méthode qui puisse être appelée même si aucun objet n'a été créé. On peut obtenir ces deux effets avec le mot-clef static. Dire que quelque chose est static signifie que la donnée ou la méthode n'est pas spécifiquement rattachée à un objet instance de cette classe. Donc, même si aucun objet de cette classe n'a jamais été créé il est possible d'appeler une méthode static ou d'accéder à une donnée static. Avec des données et des méthodes non static ordinaires il faut connaître l'objet spécifique avec lequel elles fonctionnent. Bien entendu, étant donné que les méthodes static n'ont pas besoin qu'un objet soit créé avant d'être utilisées, elles ne peuvent pas accéder directement à des membres ou des méthodes non static en appelant ces autres membres sans faire référence à un objet nommé (puisque les membres et méthodes non static doivent être rattachés à un objet spécifique).

Certains langages orientés objet emploient les expressions données de classe et méthodes de classe, ce qui signifie que les données et les méthodes n'existent que pour la classe en tant que tout et pas pour des objets particuliers de la classe. Parfois la littérature Java utilise aussi ces expressions.

Pour rendre statique une méthode ou une donnée membre il suffit de mettre le mot-clef static avant la définition. Par exemple, le code suivant crée une donnée membre static et l'initialise :

class StaticTest {
static int i = 47;
}

Maintenant, même en créant deux objets StaticTest, il n'y aura qu'une seule zone de stockage pour StaticTest.i. Tous les objets partageront le même i. Considérons :

StaticTest st1 = new StaticTest();
StaticTest st2 = new StaticTest();

à ce point, st1.i et st2.i ont la même valeur 47 puisqu'elles font référence à la même zone mémoire.

Il y a deux façons de faire référence à une variable static. Comme indiqué ci-dessus, il est possible de la nommer via un objet, en disant par exemple st2.i. Il est aussi possible d'y faire référence directement par le nom de la classe, ce qui ne peut pas être fait avec un membre non static (c'est le moyen de prédilection pour faire référence à une variable static puisque cela met en évidence la nature static de la variable).

StaticTest.i++;

L'opérateur ++ incrémente la variable. À ce point, st1.i et st2.i auront tous deux la valeur 48.

Une logique similaire s'applique aux méthodes statiques. On peut faire référence à une méthode statique soit par l'intermédiaire d'un objet, comme on peut le faire avec n'importe quelle méthode, ou avec la syntaxe spécifique supplémentaire ClassName.method( ). Une méthode statique est définie de façon similaire :

class StaticFun {
static void incr() { StaticTest.i++; }
}

On peut voir que la méthode incr( ) de StaticFun incrémente la donnée static i. On peut appeler incr( ) de façon classique, par le biais d'un objet :

StaticFun sf = new StaticFun();
sf.incr();

Ou, parce que incr( ) est une méthode statique, il est possible de l'appeler directement par sa classe :

StaticFun.incr();

Alors que static, lorsqu'il est appliqué à une donnée membre, change sans aucun doute la façon dont la donnée est créée (une pour chaque classe par opposition à une pour chaque objet dans le cas des données non statiques), lorsqu'il est appliqué à une méthode, le changement est moins significatif. Un cas important d'utilisation des méthodes static est de permettre d'appeler cette méthode sans créer d'objet. C'est essentiel, comme nous le verrons, dans la définition de la méthode main( ) qui est le point d'entrée pour exécuter une application.

Comme pour toute méthode, une méthode statique peut créer ou utiliser des objets nommés de son type, ainsi les méthodes statiques sont souvent utilisées comme « berger » pour un troupeau d'instances de son propre type.

Pour compiler et exécuter ce programme, et tous les autres programmes de ce livre, il faut d'abord avoir un environnement de programmation Java. Il y a un grand nombre d'environnements de développement, mais dans ce livre nous supposerons que vous utilisez le JDK de Sun qui est gratuit. Si vous utilisez un autre système de développement, vous devrez vous reporter à la documentation de ce système pour savoir comment compiler et exécuter les programmes.

Connectez-vous à Internet et allez sur http://java.sun.com. Là, vous trouverez des informations et des liens qui vous guideront pour télécharger et installer le JDK pour votre plate-forme.

Une fois que le JDK est installé et que vous avez configuré les informations relatives au chemin sur votre ordinateur afin qu'il puisse trouver javac et java, téléchargez et décompressez le code source de ce livre (on peut le trouver sur le CD-ROM qui est livré avec le livre ou sur www.BruceEckel.com). Ceci créera un sous-répertoire pour chacun des chapitres de ce livre. Allez dans le sous-répertoire c02 et tapez :

javac HelloDate.java

Cette commande ne devrait produire aucune réponse. Si vous obtenez un message d'erreur de quelque sorte que ce soit cela signifie que vous n'avez pas installé le JDK correctement et que vous devez corriger le problème.

Par contre, si vous obtenez simplement votre invite de commande vous pouvez taper :

java HelloDate

et vous obtiendrez en sortie le message ainsi que la date.

C'est le procédé que vous pouvez employer pour compiler et exécuter chacun des programmes de ce livre. Toutefois, vous verrez que le code source de ce livre a aussi un fichier appelé makefile dans chaque chapitre, et celui-ci contient les commandes « make » pour construire automatiquement les fichiers de ce chapitre. Reportez-vous à la page Web de ce livre sur www.BruceEckel.com pour plus de détails sur la manière d'utiliser ces makefiles.

Un des plus solides éléments de Java est que les concepteurs n'ont pas considéré que l'écriture du code est la seule activité importante - ils ont aussi pensé à sa documentation. Le plus gros problème avec la documentation de code est probablement la maintenance de cette documentation. Si la documentation et le code sont séparés, ça devient embêtant de changer la documentation chaque fois que le code change. La solution a l'air simple : relier le code et la documentation. Le moyen le plus simple de le faire est de tout mettre dans le même fichier. Toutefois, pour compléter le tableau il faut une syntaxe de commentaire particulière pour marquer la documentation particulière et un outil pour extraire ces commentaires et les mettre sous une forme exploitable. C'est ce que Java a fait.

L'outil pour extraire les commentaires est appelé javadoc. Il utilise certaines technologies du compilateur Java pour rechercher les marqueurs spécifiques des commentaires qui ont été mis dans les programmes. Il ne se contente pas d'extraire les informations repérées par ces marqueurs, mais il extrait aussi le nom de classe ou le nom de méthode adjoint au commentaire. Ainsi on parvient avec un travail minimal à générer une documentation de programme convenable.

La sortie de javadoc est un fichier HTML qui peut être visualisé avec un browser Web. Cet outil permet de créer et maintenir un unique fichier source et à générer automatiquement une documentation utile. Grâce à javadoc on a un standard pour créer la documentation et il est suffisamment simple pour qu'on puisse espérer ou même exiger une documentation avec toute bibliothèque Java.

Toutes les commandes javadoc n'apparaissent que dans les commentaires /**. Les commentaires finissent avec */ comme d'habitude. Il y a deux principales façons d'utiliser javadoc : du HTML intégré ou des « onglets doc ». Les onglets doc sont des commandes qui commencent avec un '@' et qui sont placées au début d'une ligne de commentaire (toutefois, un '*' en tête est ignoré).

Il y a trois types de commentaires de documentation qui correspondent aux éléments suivant le commentaire : classe, variable ou méthode. C'est-à-dire qu'un commentaire de classe apparaît juste avant la définition de la classe, un commentaire de variable apparaît juste avant la définition de la variable et un commentaire de méthode apparaît juste avant la définition de la méthode. Voici un exemple simple :

/** Un commentaire de classe */
public class docTest {
/** Un commentaire de variable */ 
public int i;
/** Un commentaire de méthode */
public void f() {}
}

Il faut noter que javadoc ne traite les commentaires de documentation que pour les membres public et protected. Les commentaires pour les membres private et « amis » (voir titre VII) sont ignorés et on ne verra aucune sortie (toutefois on peut utiliser le flag private pour inclure aussi les membres private). Ceci est sensé puisque seuls les membres public et protected sont accessibles en dehors du fichier, ce qui est la perspective du client du programmeur. Toutefois, tous les commentaires de classe sont inclus dans le fichier de sortie.

La sortie du code précédent est un fichier HTML qui a le même format standard que tout le reste de la documentation Java, ainsi les utilisateurs seront à l'aise avec le format et pourront facilement naviguer dans les classes. Ça vaut la peine de taper le code précédent, de le passer dans javadoc et d'étudier le fichier HTML résultant pour voir le résultat.

Javadoc passe les commandes HTML dans les documents HTML générés. Ceci permet une utilisation complète de HTML, la motivation principale étant de permettre le formatage du code comme suit :

/**
* <pre>
* System.out.println(new Date());
* </pre>
*/

On peut aussi utiliser HTML comme on pourrait le faire dans n'importe quel autre document Web pour formater du texte courant dans les descriptions :

/**
* On peut <em>même</em> insérer une liste :
* <ol>
* <li> élément un
* <li> élément deux
* <li> élément trois
* </ol>
*/

Il faut noter que dans les commentaires de documentation, les astérisques en début de ligne sont éliminés par javadoc, ainsi que les espaces en tête de ligne. Javadoc reformate tout pour assurer la conformité avec l'apparence des documentations standard. Il ne faut pas utiliser des titres tels que <h1> ou <hr> dans le HTML intégré, car javadoc insère ses propres titres et il y aurait des interférences.

Tous les types de commentaires de documentation - classes, variables et méthodes - acceptent l'intégration de HTML.

Les trois types de commentaires de documentation (classes, variables et méthodes) peuvent contenir des onglets @see, qui permettent de faire référence à de la documentation dans d'autres classes. Javadoc génèrera du HTML où les onglets @see seront des hyperliens vers d'autres documentations. Les différentes formes sont :

@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name

Chacune d'entre elles ajoute un hyperlien de type « Voir aussi » à la documentation générée. Javadoc ne vérifie pas si l'hyperlien indiqué est valide.

En plus du HTML intégré et des références @see, les documentations de classe peuvent inclure des onglets pour les informations de version et pour le nom de l'auteur. Les documentations de classe peuvent aussi être utilisées pour les interfaces (voir titre X).

IV-H-5-a. @version▲

@version version-information

IV-H-5-b. @author▲

@author author-information

IV-H-5-c. @since▲

Les documentations de variables ne peuvent contenir que du HTML intégré et des références @see.

En plus du HTML intégré et des références @see, les méthodes acceptent des onglets de documentation pour les paramètres, les valeurs de retour et les exceptions.

IV-H-7-a. @param▲

@param parameter-name description

IV-H-7-b. @return▲

@return description

IV-H-7-c. @throws▲

@throws fully-qualified-class-name description

IV-H-7-d. @deprecated▲

Voici à nouveau le premier programme Java, cette fois après avoir ajouté les commentaires de documentation :

//: c02:HelloDate.java
import java.util.*;
/** Le premier exemple de programme de Thinking in Java.
* Affiche une chaîne de caractères et la date du jour.
* @author Bruce Eckel
* @author http://www.BruceEckel.com
* @version 2.0 
*/
public class HelloDate {
/** Unique point d'entrée de la classe et de l'application
* @param args tableau de paramètres sous forme de chaînes de caractères
* @return Pas de valeur de retour
* @exception exceptions Pas d'exceptions émises
*/ 
public static void main(String[] args) {
System.out.println("Hello, it's: ");
System.out.println(new Date());
}
} ///:~

La première ligne du fichier utilise une technique personnelle qui consiste à mettre un ':' comme marqueur spécifique pour la ligne de commentaire contenant le nom du fichier source. Cette ligne contient le chemin du fichier (dans ce cas, c02 indique le Chapitre 2) suivi du nom de fichier(18). La dernière ligne finit aussi avec un commentaire et celui-ci indique la fin du listing du code source, ce qui permet de l'extraire automatiquement du texte de ce livre et de le contrôler avec un compilateur.