| Penser en Java 2nde édition | - | Sommaire | Préface | Avant-propos | Chapitre : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | Annexe : A B C D | Tables des matières | - | Thinking in Java |
Si on retourne au début pour sélectionner java.lang puis System, on voit que la classe System a plusieurs champs et si on sélectionne out on découvre que c'est un objet static PrintStream. Puisqu'il est statique, on n'a pas besoin de créer quoique ce soit. L'objet out est toujours là et il suffit de l'utiliser. Ce qu'on peut faire avec out est défini par son type : PrintStream. D'une façon très pratique, PrintStream est affiché dans la description comme un hyper lien, ainsi, en cliquant dessus on voit la liste de toutes les méthodes qu'on peut appeler pour PrintStream. Il y en a un certain nombre et elles seront décrites ultérieurement dans ce livre. Pour l'instant nous ne nous intéressons qu'à println( ), qui veut dire « écrit ce que je te donne sur la console et passe à la ligne ». Ainsi, dans tout programme Java on peut dire System.out.println("quelque chose") chaque fois qu'on souhaite écrire quelque chose sur la console.
Le nom de la classe est le même que celui du fichier. Quand on crée un programme autonome comme celui-là une des classes du fichier doit avoir le même nom que le fichier (le compilateur se plaint si on ne le fait pas). Cette classe doit contenir une méthode appelée main( ) avec la signature suivante :
Le mot-clef public signifie que la méthode est accessible au monde extérieur (décrit en détail dans le chapitre 5). Le paramètre de main( ) est un tableau d'objets de type String. Le paramètre args n'est pas utilisé dans ce programme mais le compilateur Java insiste pour qu'il soit là car il contient les paramètres invoqués sur la ligne de commande.
La ligne qui écrit la date est assez intéressante :
Considérons le paramètre : un objet Date est créé juste pour transmettre sa valeur à println( ). Dès que cette instruction est terminée, cette date est inutile et le ramasse-miettes peut venir le récupérer n'importe quand. On n'a pas à s'occuper de s'en débarrasser.
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 :
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 :
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 qe 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.
Il y a deux types de commentaires en Java. Le premier est le commentaire traditionnel, style C, dont a hérité C++. Ces commentaires commencent par /* et continuent, éventuellement sur plusieurs lignes, jusqu'à un */. Il faut remarquer que de nombreux programmeurs commencent chaque ligne de continuation de commentaire avec *, on voit donc souvent :
Il faut toutefois se rappeler que tout ce qui se trouve entre /* et */ est ignoré, il n'y a donc aucune différence avec :
La seconde forme de commentaires vient du C++. C'est le commentaire sur une seule ligne qui commence avec // et continue jusqu'à la fin de la ligne. Ce type de commentaire est pratique et souvent rencontré car il est simple. Il n'y a pas à se démener sur le clavier pour trouver / puis * (à la place il suffit d'appuyer deux fois sur la même touche) et il n'est pas nécessaire de fermer le commentaire. On trouve donc fréquemment :
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 :
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 Chapitre 5) 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 :
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 :
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 hyper liens vers d'autres documentations. Les différentes formes sont :
Chacune d'entre elles ajoute un hyper lien de type « Voir aussi » à la documentation générée. Javadoc ne vérifie pas si l'hyper lien 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 Chapitre 8).
Voici le format :
dans lequel version-information est n'importe quelle information significative que l'on souhaite inclure. Quand le flag -version est mis sur la ligne de commande de javadoc, les informations de version seront exploitées, particulièrement dans la documentation HTML.
Voici le format :
dans lequel author-information est, a priori, votre nom mais il peut aussi contenir une adresse email ou toute autre information appropriée. Quand le flag -author est mis sur la ligne de commande javadoc, les informations sur l'auteur seront exploitées, particulièrement dans la documentation HTML.
On peut avoir plusieurs onglets d'auteur pour une liste d'auteurs mais ils doivent être placés consécutivement. Toutes les informations d'auteurs seront regroupées dans un unique paragraphe dans le code HTML généré.
Cet onglet permet d'indiquer la version du code qui a commencé à utiliser une caractéristique particulière. On la verra apparaître dans la documentation HTML de Java pour indiquer quelle version de JDK erst utilisée.
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.
Voici le format :
dans lequel parameter-name est l'identificateur dans la liste de paramètres et description est du texte qui peut se prolonger sur les lignes suivantes. La description est considérée comme terminée quand un nouvel onglet de documentation est trouvé. On peut en avoir autant qu'on veut, a priori un pour chaque paramètre.
Voici le format :
dans lequel description indique la signification de la valeur de retour. Le texte peut se prolonger sur les lignes suivantes.
Les exceptions seront introduites dans le Chapitre 10 mais, brièvement, ce sont des objets qui peuvent être émis (thrown) par une méthode si cette méthode échoue. Bien qu'une seule exception puisse surgir lors de l'appel d'une méthode, une méthode donnée est susceptible de produire n'importe quel nombre d'exceptions de types différents, chacune d'entre elles nécessitant une description. Ainsi, le format de l'onglet d'exception est :
dans lequel fully-qualified-class-name indique sans ambiguité un nom de classe d'exception qui est définie quelque part, et description (qui peut se prolonger sur les lignes suivantes) précise pourquoi ce type particulier d'exception peut survenir lors de l'appel de la méthode.
Ceci est utilisé pour marquer des fonctionnalités qui ont été remplacées par d'autres qui sont meilleures. L'onglet deprecated suggère de ne plus utiliser cette fonctionnalité particulière étant donné qu'elle sera probablement supprimée ultérieurement. Une méthode marquée @deprecated fait produire un warning par le compilateur si elle est utilisée.
Voici à nouveau le premier programme Java, cette fois après avoir ajouté les commentaires de documentation :
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 [25]. 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.
Le standard non officiel de Java consiste à mettre en majuscule la première lettre des noms de classes. Si le nom de classe est composé de plusieurs mots, ils sont accolés (c'est à dire qu'on ne sépare pas les noms avec un trait bas) et la première lettre de chaque mot est mise en majuscule ainsi :
Pour pratiquement tout les reste : méthodes, champs (variables membres) et les noms des références d'objets, le style retenu est comme pour les classes sauf que la première lettre de l'identificateur est une minuscule. Par exemple :
Bien entendu il faut se rappeler que l'utilisateur doit aussi taper tous ces longs noms, donc soyez clément.
Le code Java qu'on voit dans les bibliothèques de Sun respecte aussi le placement des accolades ouvrantes et fermantes qui est utilisé dans ce livre.
