t
t
t
t
t t 2) Tout est « objet »
tttt
2) Tout est « objet »
Texte original t Traducteur : Raczy
t
t
///
Ce chapitre contient 4 pages
1 2 3 4
\\\
t t t
t t t
t
t t t
At the beginning of each program file, you must place the import statement to bring in any extra classes you’ll need for the code in that file. Note that I say “extra;” that’s because there’s a certain library of classes that are automatically brought into every Java file: java.lang. Start up your Web browser and look at the documentation from Sun. (If you haven’t downloaded it from java.sun.com or otherwise installed the Java documentation, do so now). If you look at the list of the packages, you’ll see all the different class libraries that come with Java. Select java.lang. This will bring up a list of all the classes that are part of that library. Since java.lang is implicitly included in every Java code file, these classes are automatically available. There’s no Date class listed in java.lang, which means you must import another library to use that. If you don’t know the library where a particular class is, or if you want to see all of the classes, you can select “Tree” in the Java documentation. Now you can find every single class that comes with Java. Then you can use the browser’s “find” function to find Date. When you do you’ll see it listed as java.util.Date, which lets you know that it’s in the util library and that you must import java.util.* in order to use Date. t Au début de chaque fichier de programme il faut mettre la déclaration import pour importer toutes les classes supplémentaires qui seront nécessaires pour le code dans ce fichier. Il faut noter que je dis « supplémentaires » ; c'est parce qu'il y a une bibliothèque de classes qui est automatiquement importée dans tous les fichiers Java : java.lang. En démarrant un browser Web et en chargeant la documentation de Sun (si elle n'a pas été téléchargée de java.sun.com ou si la documentation Java n'a pas encore été installée, il faut le faire maintenant), si on regarde à la liste des package, on voit toutes les bibliothèques de classes qui sont fournies avec Java. Sélectionnons java.lang. Ceci fait apparaître la liste de toutes les classes contenues dans cette bibliothèque. Étant donné que java.lang est implicitement inclus dans tous les fichiers source Java, ces classes sont automatiquement disponibles. Il n'y a pas de classe Date dans java.lang, ce qui veut dire qu'il faut importer une autre bibliothèque pour l'utiliser. Si on ne sait pas dans quelle bibliothèque se trouve une classe donnée, ou si on veut voir toutes les classes, on peut sélectionner « Tree » dans la documentation Java. Maintenant on peut trouver n'importe laquelle des classes fournies avec Java. On peut alors utiliser la fonction « chercher » du browser pour trouver Date. Une fois que c'est fait on voit qu'elle est connue en tant que java.util.Date, ce qui permet de savoir qu'elle se trouve dans la bibliothèque util et qu'il faut déclarer import java.util.* de façon à pouvoir utiliser Date.
t t t
If you go back to the beginning, select java.lang and then System, you’ll see that the System class has several fields, and if you select out you’ll discover that it’s a static PrintStream object. Since it’s static you don’t need to create anything. The out object is always there and you can just use it. What you can do with this out object is determined by the type it is: a PrintStream. Conveniently, PrintStream is shown in the description as a hyperlink, so if you click on that you’ll see a list of all the methods you can call for PrintStream. There are quite a few and these will be covered later in this book. For now all we’re interested in is println( ), which in effect means “print what I’m giving you out to the console and end with a new line.” Thus, in any Java program you write you can say System.out.println(“things”) whenever you want to print something to the console. t 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.
t t t
The name of the class is the same as the name of the file. When you’re creating a stand-alone program such as this one, one of the classes in the file must have the same name as the file. (The compiler complains if you don’t do this.) That class must contain a method called main( ) with the signature shown: t 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 :
t t t
public static void main(String[] args) {
t
public static void main(String[] args);
t t t
The public keyword means that the
method is available to the outside world (described in detail in Chapter 5). The
argument to main( ) is an array of String objects. The
args won’t be used in this program, but the Java compiler insists
that they be there because they hold the arguments invoked on the command
line.
t 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.
t t t
The line that prints the date is quite
interesting:

t La ligne qui écrit la date est assez intéressante :
t t t
System.out.println(new Date());
t
System.out.println(new Date());
t t t
Consider the argument: a Date
object is being created just to send its value to println( ). As
soon as this statement is finished, that Date is unnecessary, and the
garbage collector can come along and get it anytime. We don’t need to
worry about cleaning it
up.
t 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.
t t t


Compiling and running


t

Compilation et exécution

t t t
To
compile
and run this program, and all the other programs in this book, you must first
have a Java programming environment. There are a number of third-party
development environments, but in this book we will assume that you are using the
JDK from Sun, which is free. If you are using another development system, you
will need to look in the documentation for that system to determine how to
compile and run programs.
t 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.
t t t
Get on the Internet and go to
java.sun.com. There you will find information and links that will lead
you through the process of downloading and installing the JDK for your
particular platform.
t 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.
t t t
Once the JDK is installed, and
you’ve set up your computer’s path information so that it will find
javac and java, download and unpack the
source code for this book (you can find it on the CD ROM that’s bound in
with this book, or at www.BruceEckel.com). This will create a
subdirectory for each chapter in this book. Move to subdirectory c02 and
type:

t 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 :
t t t
javac HelloDate.java
t
javac HelloDate.java
t t t
This command should produce no response.
If you get any kind of an error message it means you haven’t installed the
JDK properly and you need to investigate those problems.
t 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.
t t t
On the other hand, if you just get your
command prompt back, you can type:

t Par contre, si vous obtenez simplement votre invite de commande vous pouvez taper :
t t t
java HelloDate
t
java HelloDate
t t t
and you’ll get the message and the
date as output.
t et vous obtiendrez en sortie le message ainsi que la date.
t t t
This is the process you can use to
compile and run each of the programs in this book. However, you will see that
the source code for this book also has a file called makefile in each
chapter, and this contains “make” commands for automatically
building the files for that chapter. See this book’s Web page at
www.BruceEckel.com for details on how to use the
makefiles.
t 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.
t t t


Comments and embedded
documentation


t

Commentaires et documentation intégrée

t t t
There are two types of comments in Java.
The first is the traditional C-style comment that was inherited by C++. These
comments begin with a /* and continue, possibly across many lines, until
a */. Note that many programmers will begin each line of a continued
comment with a *, so you’ll often see:

t 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 :
t t t
/* This is a comment
*  that continues
*  across lines
*/
t
/* Ceci est un commentaire
* qui continue
* sur plusieurs lignes
*/
t t t
Remember, however, that everything inside the /* and */ is ignored, so there’s no difference in saying: t Il faut toutefois se rappeler que tout ce qui se trouve entre /* et */ est ignoré, il n'y a donc aucune différence avec :
t t t
/* This is a comment that
continues across lines */
t
/* Ceci est un commentaire qui
   continue sur plusieurs lignes */
t t t
The second form of comment comes from C++. It is the single-line comment, which starts at a // and continues until the end of the line. This type of comment is convenient and commonly used because it’s easy. You don’t need to hunt on the keyboard to find / and then * (instead, you just press the same key twice), and you don’t need to close the comment. So you will often see: t 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 :
t t t
// this is a one-line comment t
// Ceci est un commentaire sur une seule ligne
t t t


Comment documentation


t

Commentaires de documentation

t t t
One of the thoughtful parts of the Java
language is that the designers didn’t consider writing code to be the only
important activity—they also thought about documenting it. Possibly the
biggest problem with documenting code has been maintaining that documentation.
If the documentation and the code are separate, it becomes a hassle to change
the documentation every time you change the code. The solution seems simple:
link the code to the documentation. The easiest way to do this is to put
everything in the same file. To complete the picture, however, you need a
special comment syntax to mark special documentation, and a tool to extract
those comments and put them in a useful form. This is what Java has
done.
t 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.
t t t
The tool to extract the comments is
called javadoc. It uses some of the technology from the Java compiler to
look for special comment tags you put in your programs. It not only extracts the
information marked by these tags, but it also pulls out the class name or method
name that adjoins the comment. This way you can get away with the minimal amount
of work to generate decent program documentation.
t 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.
t t t
The output of javadoc is an HTML file
that you can view with your Web browser. This tool allows you to create and
maintain a single source file and automatically generate useful documentation.
Because of javadoc we have a standard for creating documentation, and it’s
easy enough that we can expect or even demand documentation with all Java
libraries.
t 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.
t t t


Syntax


t

Syntaxe

t t t
All of the javadoc commands occur only
within /** comments. The comments end with */ as usual. There are
two primary ways to use javadoc: embed HTML, or use “doc tags.” Doc
tags are commands that start with a ‘@’ and are placed at the
beginning of a comment line. (A leading ‘*’, however, is
ignored.)
t 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é).
t t t
There are three “types” of
comment documentation, which correspond to the element the comment precedes:
class, variable, or method. That is, a class comment appears right before the
definition of a class; a variable comment appears right in front of the
definition of a variable, and a method comment appears right in front of the
definition of a method. As a simple example:

t 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 :
t t t
/** A class comment */
public class docTest {
  /** A variable comment */
  public int i;
  /** A method comment */
  public void f() {}
}
t
/** Un commentaire de classe */
public class docTest {
  /** Un commentaire de variable */
  public int i;
  /** Un commentaire de méthode */
  public void f() {}
}
t t t
Note that javadoc will process comment documentation for only public and protected members. Comments for private and “friendly” members (see Chapter 5) are ignored and you’ll see no output. (However, you can use the -private flag to include private members as well.) This makes sense, since only public and protected members are available outside the file, which is the client programmer’s perspective. However, all class comments are included in the output. t 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.
t t t
The output for the above code is an HTML file that has the same standard format as all the rest of the Java documentation, so users will be comfortable with the format and can easily navigate your classes. It’s worth entering the above code, sending it through javadoc and viewing the resulting HTML file to see the results. t 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.
t t t

Embedded HTML

t

HTML intégré

t t t
Javadoc passes HTML commands through to the generated HTML document. This allows you full use of HTML; however, the primary motive is to let you format code, such as: t 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 :
t t t
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
t
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
t t t
You can also use HTML just as you would in any other Web document to format the regular text in your descriptions: t 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 :
t t t
/**
* You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/
t
/**
* On peut <em>même</em> insérer une liste :
* <ol>
* <li> élément un
* <li> élément deux
* <li> élément trois
* </ol>
*/
t t t
Note that within the documentation comment, asterisks at the beginning of a line are thrown away by javadoc, along with leading spaces. Javadoc reformats everything so that it conforms to the standard documentation appearance. Don’t use headings such as <h1> or <hr> as embedded HTML because javadoc inserts its own headings and yours will interfere with them. t 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.
t t t
All types of comment documentation—class, variable, and method—can support embedded HTML. t Tous les types de commentaires de documentation -- classes, variables et méthodes -- acceptent l'intégration de HTML.
t t t

@see: referring to other classes

t

@see : faire référence aux autres classes

t t t
All three types of comment documentation (class, variable, and method) can contain @see tags, which allow you to refer to the documentation in other classes. Javadoc will generate HTML with the @see tags hyperlinked to the other documentation. The forms are: t 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 :
t t t
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
t
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
t t t
Each one adds a hyperlinked “See Also” entry to the generated documentation. Javadoc will not check the hyperlinks you give it to make sure they are valid. t 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.
t t t

Class documentation tags

t

Class documentation tags

t t t
Along with embedded HTML and @see references, class documentation can include tags for version information and the author’s name. Class documentation can also be used for interfaces (see Chapter 8). t 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).
t t t

@version

t

@version

t t t
This is of the form: t Voici le format :
t t t
@version version-information
t
@version version-information
t t t
in which version-information is
any significant information you see fit to include. When the -version
flag is placed on the javadoc command line, the version information will be
called out specially in the generated HTML documentation.
t 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.
t t t


@author


t

@author

t t t
This is of the form:

t Voici le format :
t t t
@author author-information
t
@author author-information
t t t
in which author-information is,
presumably, your name, but it could also include your email address or any other
appropriate information. When the -author flag is placed on the javadoc
command line, the author information will be called out specially in the
generated HTML documentation.
t 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.
t t t
You can have multiple author tags for a
list of authors, but they must be placed consecutively. All the author
information will be lumped together into a single paragraph in the generated
HTML.
t 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é.
t t t


@since


t

@since

t t t
This tag allows you to indicate the
version of this code that began using a particular feature. You’ll see it
appearing in the HTML Java documentation to indicate what version of the JDK is
used.
t 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.
t t t


Variable documentation tags


t

Les onglets de documentation de variables

t t t
Variable documentation can include only
embedded HTML and @see
references.
t Les documentations de variables ne peuvent contenir que du HTML intégré et des références @see.
t t t


Method documentation tags


t

Les onglets de documentation de méthodes

t t t
As well as embedded documentation and
@see references, methods allow documentation tags for parameters, return
values, and exceptions.
t 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.
t t t


@param


t

@param

t t t
This is of the form:

t Voici le format :
t t t
@param parameter-name description
t
@param parameter-name description
t t t
in which parameter-name is the
identifier in the parameter list, and description is text that can
continue on subsequent lines. The description is considered finished when a new
documentation tag is encountered. You can have any number of these, presumably
one for each parameter.
t 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.
t t t


@return


t

@return

t t t
This is of the form:

t Voici le format :
t t t
@return description
t
@return description
t t t
in which description gives you the
meaning of the return value. It can continue on subsequent
lines.
t dans lequel description indique la signification de la valeur de retour. Le texte peut se prolonger sur les lignes suivantes.
t t t


@throws


t

@throws

t t t
Exceptions will be demonstrated in
Chapter 10, but briefly they are objects that can be “thrown” out of
a method if that method fails. Although only one exception object can emerge
when you call a method, a particular method might produce any number of
different types of exceptions, all of which need descriptions. So the form for
the exception tag is:

t 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 :
t t t
@throws fully-qualified-class-name description
t
@throws fully-qualified-class-name description
t t t
in which
fully-qualified-class-name gives an unambiguous name of an exception
class that’s defined somewhere, and description (which can continue
on subsequent lines) tells you why this particular type of exception can emerge
from the method call.
t 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.
t t t


@deprecated


t

@deprecated

t t t
This is used to tag features that were
superseded by an improved feature. The deprecated tag is a suggestion that you
no longer use this particular feature, since sometime in the future it is likely
to be removed. A method that is marked @deprecated causes the compiler to
issue a warning if it is
used.
t 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.
t t t


Documentation example


t

Exemple de documentation

t t t
Here is the first Java program again,
this time with documentation comments added:

t Voici à nouveau le premier programme Java, cette fois après avoir ajouté les commentaires de documentation :
t t t
//: c02:HelloDate.java
import java.util.*;

/** The first Thinking in Java example program.
* Displays a string and today's date.
* @author Bruce Eckel
* @author www.BruceEckel.com
* @version 2.0
*/
public class HelloDate {
  /** Sole entry point to class & application
   * @param args array of string arguments
   * @return No return value
   * @exception exceptions No exceptions thrown
  */
  public static void main(String[] args) {
    System.out.println("Hello, it's: ");
    System.out.println(new Date());
  }
} ///:~
t
//: 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());
  }
} ///:~
t t t
The first line of the file uses my own technique of putting a ‘:’ as a special marker for the comment line containing the source file name. That line contains the path information to the file (in this case, c02 indicates Chapter 2) followed by the file name[24]. The last line also finishes with a comment, and this one indicates the end of the source code listing, which allows it to be automatically extracted from the text of this book and checked with a compiler. t 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.
t t t

Coding style

t

Style de programmation

t t t
The unofficial standard in Java is to capitalize the first letter of a class name. If the class name consists of several words, they are run together (that is, you don’t use underscores to separate the names), and the first letter of each embedded word is capitalized, such as: t 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 :
t t t
class AllTheColorsOfTheRainbow { // ...
t
class AllTheColorsOfTheRainbow { // ...
t t t
For almost everything else: methods,
fields (member variables), and object reference names, the accepted style is
just as it is for classes except that the first letter of the identifier
is lowercase. For example:

t 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 :
t t t
class AllTheColorsOfTheRainbow {
  int anIntegerRepresentingColors;
  void changeTheHueOfTheColor(int newHue) {
    // ...
  }
  // ...
}
t
class AllTheColorsOfTheRainbow {
  int anIntegerRepresentingColors;
  void changeTheHueOfTheColor(int newHue) {
    // ...  
  }
  // ...
}
t t t
Of course, you should remember that the user must also type all these long names, and so be merciful. t Bien entendu il faut se rappeler que l'utilisateur doit aussi taper tous ces longs noms, donc soyez clément.
t t t
The Java code you will see in the Sun libraries also follows the placement of open-and-close curly braces that you see used in this book. t 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.
t t t
t t t
t t
\\\
///
t t t
t
     
Sommaire Le site de Bruce Eckel