Convention d'écriture en Java

1 1 1 1 1 1 1 1 1 1 Rating 0.00 (0 Votes)
Submit to DeliciousSubmit to DiggSubmit to FacebookSubmit to Google PlusSubmit to StumbleuponSubmit to TechnoratiSubmit to TwitterSubmit to LinkedIn

Convention d'écriture en Java

Ce tutoriel rassemble quelques règles usuelles de présentation de programmes en Java.

Il est important de noter que ces règles sont bien des conventions et ne font pas partie de la syntaxe de Java. Vous pouvez parfaitement écrire des programmes Java corrects mais illisibles ou très confus.

Mais si une syntaxe correcte est nécessaire pour que la machine vous comprenne, une écriture claire et cohérente est nécessaire pour que d'autres humains vous comprennent.

Fichiers

Les noms de fichiers de source Java ont le suffixe .java. Les noms de fichiers compilés (bytecode) ont le suffixe .class.

Chaque fichier source Java contient une seule classe ou interface publique. Le nom du fichier (sans le suffixe .java) est obligatoirement le nom de cette classe ou interface publique. Si on y met des classes ou interfaces privées, la classe ou interface publique doit être la première à être définie dans le fichier.

On organisera le contenu de chaque fichier dans l'ordre suivant : Commentaires de début, comportant entre autres le nom de la classe, le nom de l'auteur, la date de création et de dernière mise à jour. Déclaration du package éventuel, suivie des importations éventuelles, par exemple :

package test.hello;
import java.awt.*;

Indentation

Utiliser de préférence 4 espaces comme unité d'indentation. Règle de base : le niveau d'indentation correspond au degré d'imbrication.

Soyez cohérent dans vos alignements d'accolades ouvrantes et fermantes (utilisez partout la même convention). Le document SUN recommande de mettre l'accolade ouvrante à la fin de la ligne où commence le bloc concerné, et l'accolade fermante sur une ligne à part, indentée au niveau de l'instruction qui a entraîné l'ouverture du bloc, sauf pour les méthodes à corps vide, pour lesquelles l'accolade fermante suit immédiatement l'accolade ouvrante. Exemples :

class Test extends Object {
    int var1;
    int var2;
    Test(int i, int j) {
        var1 = i;
        var2 = j;
    }
    int methodeVide() {}
    void calculs() {
        ...
        if (var1 > 0) {
            var2--;
            ...
        }
       ...
        while (var1 != var2) {
            ...
        }
    }
    ...
}

Éviter les lignes trop longues (plus de 80 caractères), et souvenez-vous que vous pouvez toujours écrire une expression très longue sur plusieurs lignes. Dans ce cas, on cherchera à les couper aux endroits qui laissent la plus grande lisibilité : après une virgule, avant un opérateur, au niveau de parenthésage le plus englobant possible, aligner la nouvelle ligne avec le début de l'expression qui est au même niveau à la ligne précédente, si tout ce qui précède marche mal, indenter tout simplement de 4 ou 8 espaces.

Quelques exemples :

fonc(expressionTresLongue1, expressionTresLongue2, expressionTresLongue3,
     expressionTresLongue4, expressionTresLongue5);
var = fonc1(expressionTresLongue1,
            fonc2(expressionTresLongue2,
                  expressionTresLongue3));
impotAPayer = ageDuCapitaine * (longueur + largeur - hauteur)
              + 4 * tailleChemise;

Pour les instructions "if", s'il faut présenter la condition sur plusieurs lignes, indenter de 8 espaces au lieu de 4 pour que l'instruction qui suit reste lisible :

if ((condition1 && condition2)
        || (condition3 && condition4)
        || (condition5 && condition6)) {
    faireQuelqueChose()   // reste lisible
    ...
}

Commentaires

Commentaires de programmation

On les utilise soit pour "masquer" une partie du code, en cours de développement, soit pour expliquer certains détails de mise en oeuvre. Ils peuvent être mis sous la forme de l'un des styles suivants :

Blocs de commentaires : servent à expliciter des fichiers, des méthodes, des structures de données et des algorithmes. Les précéder d'une ligne blanche, et les présenter comme suit :

/*
 * Ceci est un bloc de commentaire.
 * Il peut comporter plusieurs lignes, chacune commençant par une
 * étoile entourée de deux espaces, pour la lisibilité de l'ensemble
 */

Une ligne de commentaire : si votre commentaire ne tient pas sur une ligne, ne faites pas suivre deux lignes de commentaires ; utilisez de préférence un bloc de commentaires. Exemple de ligne de commentaire :

if (condition) {
    /* Traiter le cas où tout va bien */
    ....
}

Commentaires de fin de ligne : ils peuvent prendre les deux formes /* ... */ ou // ..., la deuxième servant en outre à "masquer" une partie du code en cours de développement ou de déboguage. Exemples :

if (a == 2) {
    return TRUE;      /* Cas particulier */
}
else if (toto > 1) {
    // Permuter les deux valeurs
    ...
}
else
    return FALSE;     // Explications
// if (tata > 1) {
//
//    // Trois valeurs à permuter
//    ...
//}
//else
//    return FALSE;

Commentaires de documentation

Ces commentaires sont traités comme les autres par le compilateur, mais sont interprétés par l'outil javadoc, qui permet de créer des pages WWW de documentation de vos programmes. Pour une introduction à javadoc, voir son site de référence2, où vous trouverez aussi un manuel avec des exemples pour Windows. Un commentaire de documentation commence par /** et se termine par */. Exemples de commentaires de documentation :

  • Pour une classe :
/**
 * Cette classe est une spécialisation de la classe générale des clients.
 * @author   Jean Lingénieur
 * @see      Client
 */
class ClientPrivilegie extends Client
{
...
}
  • Pour une méthode :
    /**
     * Rend la somme TTC à payer après application de la TVA et d'une
     * réduction éventuelle.
     * @param    sommeHT le montant hors taxes et avant réduction de la commande
     * @return   montant TTC net à payer
     */
    double sommeTTC(double sommeHT) {
        ...
    }

Déclarations et instructions

Il est recommandé de ne mettre qu'une déclaration par ligne, et de regrouper les déclarations en début de bloc. Essayez d'initialiser les variables locales dès leur déclaration (il y a bien sûr des cas où cela est difficile ou impossible, comme quand l'initalisation dépend d'un calcul préalable).

Par souci de clarté, évitez de masquer des variables à un certain niveau par des variables de même nom à un niveau d'imbrication inférieur, comme dans :

int total;
...
fonction() {
    if (condition) {
        int total;       // à éviter !!
        ...
    }
    ...
}

Mettez une seule instruction par ligne ; évitez par exemple :

compte++; valeur -= compte;    // à éviter !!

N'utilisez des parenthèses avec l'instruction return que lorsqu'elles clarifient la lecture du code.

Noms

Choisissez toujours des noms significatifs et non ambigus quant au concept qu'ils désignent. Tenez-vous en à une des deux grandes règles de composition : majuscules à chaque nouveau mot de la composition (ageDuCapitaine) ou soulignés (age_du_capitaine). Dans le tableau suivant, nous choisissons la première.

Type Règles de nommage Exemples
Classes La première lettre doit être une majuscule. Éviter les acronymes, choisir des noms simples et descriptifs. class Image;class ClientPrivilégié;
Interfaces Mêmes règles que pour les classes interface ImageAccesDirect;interface Stockage;
Méthodes Les noms de méthodes (fonctions) doivent refléter une action. Choisir de préférence des verbes. Première lettre en minuscules. afficher();getValue();setValue();
Variables Première lettre en minuscules. Noms relativement courts mais descriptifs (mnémoniques). Éviter les noms à une lettre, sauf pour compteurs internes et variables temporaires. int i;float largeur;String nomDuCapitaine;
Constantes En majuscules. Le séparateur devient donc forcément un souligné. final static int VAL_MAX = 999;
Submit to DeliciousSubmit to DiggSubmit to FacebookSubmit to Google PlusSubmit to StumbleuponSubmit to TechnoratiSubmit to TwitterSubmit to LinkedIn