Ce document a pour but de montrer quelques règles communément adoptées par la communauté des programmeurs Java et destinées à simplifier le relecture du code source. Les conventions adoptées ici sont quelque peu différentes de celles de Sun, en particulier pour ce qui concerne les identificateurs des membres de classe.
Bien que les règles édictées par Sun soient beaucoup moins strictes que cela, nous vous recommandons de suivre les principes suivants :
Bien que la plupart des compilateurs ne rechignent pas, l'usage des lettres accentuées n'est pas recommandé.
Tout nom de classe ou d'interface doit commencer par une Majuscule suivie de minuscules. Si ce nom est constitué de plusieurs mots, on utilisera une majuscule pour chaque nouveau mot. L'usage du caractère tiret bas est proscrit car fatiguant la vision. Voici des exemples de noms de classes corrects :
PoursuiteCible AdaptateurVehicule CompositeGraphique
A l'exception notable des constantes, le nom d'un attribut d'instance commence toujours par une minuscule alors que celui d'un membre de classe commence par une Majuscule. A l'instar des noms de classes ou d'interfaces, on utilise exclusivement des combinaisons de minuscules.
La convention de nommage des paramètres ou des variables locales des méthodes suit celle des attributs d'instance.
Voici quelques exemples :
int index; Point pointDeBase; int compteurElements; java.awt.Color couleur;
int NombreObjetsGraphiques; HashMap GammeDesCouleurs;
Point getPointDeBase(); void changerCouleur(Color nouvelleCouleur); void deplacerVers(int nouvelleAbscisse, int nouvelleOrdonnee);
Color GetCouleurDeGamme(int index); Color GetCouleurDeGamme(String nom);
Par similarité avec le langage C, l'identificateur d'une constante est toujours totalement en MAJUSCULES. Une fois n'est pas coutume, l'on utilise le caractère souligné pour séparer les différents mots composant le nom d'une constante. Exemples :
public static final int NOMBRE_MAXIMAL_AUTORISE=10; public static final double SEUIL_CORRELATION=0.7;
En règle général, il est toujours recommandé de placer une accolade sur une ligne isolée. La taille la plus courante d'indentation étant de 2 colonnes.
if (condition) instruction simple;
if (condition)
{
bloc d'instructions;
}
if (condition1)
{
bloc d'instructions;
}
else
{
bloc d'instructions;
}
if (condition1)
{
bloc d'instructions;
}
else if (condition2)
{
bloc d'instructions;
}
else
{
bloc d'instructions;
}
switch (discriminant)
{
case cas1:
instruction1;
instruction2;
break;
case cas2:
case cas3:
instructions;
break;
default:
instruction;
}
La disposition des boucles obéit aux mêmes règles que celles des instructions conditionnelles. On veillera donc à bien isoler la partie condition sur une ligne séparée.
while (condition) instruction simple;
while (condition)
{
instructions;
}
Dans ce cas, et afin d'éviter des confusions, il est préconisé de placer le while directement à la suite de l'accolade fermante si vous utilisez un bloc d'instructions. On obtient alors l'une des 2 formes suivants
do instruction simple; while (condition);
do
{
instructions;
} while (condition);
Les règles concernant le placement relatif de l'entête et du corps sont similaires à celles régissant la boucle while. Toutefois, il peut être utile de spécifier le placement des trois sous parties de l'entête. On admet 2 présentations différentes :
Exemples :
for (initialisation ; test ; mise a jour) instruction simple;
for (initialisation ;
test ;
mise a jour)
{
instructions;
}
Le choix d'une des 2 présentations pour les trois sous instructions de l'entête est dicté par la la longueur des lignes de code résultantes.
En règle générale, dès que l'on souhaite séparer sur plusieurs lignes une expression qui contient des parenthèses, on aligne verticalement celles-ci. Si l'expression ne comprend pas de parenthèses, on ajoute 2 caractères d'indentation. Exemples :
int somme = 10 + 12 + 3 + 4
+ 25;
if (((a < 5) && (b > 3)) ||
(i > 7) ||
((a > 9) && (c < 2)))
Dans le cas d'expressions très complexes, il existe une variante intéressante au cas précédent :
if (
(
(a < 5) && (b > 3)
)
||
(i > 7)
||
(
(a > 9) && (c < 2)
)
)
Le bloc try est indenté à la manière d'un bloc d'instructions. Les blocs catch sont également traités de cette manière :
try
{
Instructions protégées;
}
catch (Exception1 &e)
{
Traitement1;
}
catch (Exception2 &e)
{
Traitement2;
}
De manière générale, on commence par les déclarations publiques avant les parties plus privées de la classe de manière à donner la priorité de lecture aux informations qui sont disponibles aux clients de la classe.
De même, il faut éviter de définir plusieurs classes dans le même fichier source. La notion de package est faite pour cela.
Au début de chaque classe, veillez à insérer un cartouche expliquant le but de la classe, ainsi que ses éventuelles classes imbriquées. L'utilisation de commentaires commençant par /** permet de générer automatiquement la documentation à l'aide de l'utilitaire javadoc.
On ne met qu'un seul attribut (respectivement, une seule variable) par ligne de déclaration. Cela simplifie considérablement la lecture, surtout s'il y a des initialisations ! En outre, on veillera à aligner les noms des identificateurs. Un exemple est donné à la rubrique Attributs d'instance.
Une méthode se présente à la manière d'un bloc de code précédé d'un entête, lequel est composé des éléments suivants :
Il y a plusieurs méthodes de présentation de cet entête. D'aucuns préconisent d'isoler sur une ligne séparée le type de retour, personnellement, je préfère le laisser sur la même ligne que l'identificateur accompagné du premier paramètre. Les autres paramètres étant alignés verticalement avec le premier. Ce qui nous donne :
type_de_retour identificateur(type_premier_parametre identificateur1,
type_second_parametre identificateur2,
...)
{
Declarations locales
Code
}
Au début de chaque méthode, il est fortement recommandé de placer un commentaire expliquant le rôle de la méthode ainsi que la signification de chacun des paramètres. Ce commentaire pourra être utilisé par l'utilitaire javadoc lors de la création de la documentation si vous prenez soin de le faire commencer par /**.