Annexe 1 : Guide de style de programmation Java

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.

Les identificateurs :

Bien que les règles édictées par Sun soient beaucoup moins strictes que cela, nous vous recommandons de suivre les principes suivants :

  1. Les identificateurs Java doivent commencer par une lettre minuscule, une lettre minuscule ou un caractère souligné (_)
  2. Ils peuvent ensuite contenir n'importe quelle combinaison des caractères suivants :

Bien que la plupart des compilateurs ne rechignent pas, l'usage des lettres accentuées n'est pas recommandé.

Classes et Interfaces

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

Membres

Règle générale :

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 :

Attributs d'instance :

int            index;
Point          pointDeBase;
int            compteurElements;
java.awt.Color couleur;

Attributs de classe :

int            NombreObjetsGraphiques;
HashMap        GammeDesCouleurs;

Méthodes d'instance

Point          getPointDeBase();
void           changerCouleur(Color nouvelleCouleur);
void           deplacerVers(int nouvelleAbscisse, int nouvelleOrdonnee);

Méthodes de classe

Color          GetCouleurDeGamme(int index);
Color          GetCouleurDeGamme(String nom);

Les constantes

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;

Positionnement du code et indentation

Blocs de code

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.

Instructions conditionnelles

Blocs if

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;
}

Blocs switch

switch (discriminant)
{
  case cas1:
    instruction1;
    instruction2;
    break;
  case cas2:
  case cas3:
    instructions;
    break;
  default:
    instruction;
}

Les boucles

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.

Boucle while

while (condition)
  instruction simple;
while (condition)
{
  instructions;
}

Boucle do while

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);

Boucle for

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.

Présentation des expressions arithmétiques et booléennes

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)
    )
   )

Les exceptions

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;
}

La présentation des classes

Aspects généraux

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.

Déclaration des attributs ou des variables locales

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.

Définition des méthodes

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 /**.