Normes de programmation pour JAVA

1. Nomenclature

2. Organisation d'un fichier source

2.1. Commentaire global

2.2. Instructions package et import

2.3. La déclaration de la classe ou de l'interface

3. Commentaires

3.1. Commentaire de documentation de classe

3.2. Commentaire des méthodes et des constructeurs

3.3. Commentaire pour les variables de classe et d'instance

4. Indentation

5. Déclarations

5.1. Nombre de déclaration par ligne

5.2. Initialisation

5.3. Placement

5.4. Déclaration des classes (ou interface) et des méthodes

6. Les énoncés

6.1. Énoncés simples

6.2. Énoncés avec accolades

6.3. Énoncés if, if-else, if elseif else

6.4. Énoncé for

6.5. Énoncé while

6.6. Énoncé do-while

6.7. Énoncé switch

6.8. Énoncé try-catch

7. Quelques règles de programmation

1  Nomenclature

2  Organisation d'un fichier source

• Commentaire global
• Instructions package et import
• La déclaration de la classe ou de l'interface 
  

Ces trois parties sont définies dans les sections qui suivent.

2.1  Commentaire global

• Le nom de la classe
• Le nom de l'auteur
• La date de création
• Une liste des dates des modifications importantes avec une brève description de la modification en ordre chronologique
  

Voici un exemple de commentaire global:

/*
 * Classe:          Cercle
 *
 * Auteur:          Sébastien Paquet
 *
 * 13 mai 2000      Création
 * 25 mai 2000      Ajout de la méthode XXX
 * 12 juin 2000     Modification de la méthode YYY
 */

2.2  Instructions package et import

package java.awt;

import java.awt.peer.CanvasPeer;

2.3  La déclaration de la classe ou de l'interface

3  Commentaires

• Les commentaires javadoc /**...*/
• Les commentaires qui s'étendent sur plus d'une ligne /*..*/
• Les commentaires de fin de ligne // 
  

Vous devez utiliser les commentaires pour chacune des parties de votre code qui mérite d'être commentées. C'est au programmeur de juger de la pertinence d'un commentaire. Il est à noter qu'il est possible et conseillé d'utiliser les instructions HTML pour ajuster la présentation des commentaires javadoc. Par contre, les sections suivantes vous présenteront les commentaires obligatoires.

3.1  Commentaire de documentation de classe

/**
 * Graphics is the abstract base class for all graphics contexts
 * which allow an application to draw onto components realized on
 * various devices or onto off-screen images.
 * A Graphics object encapsulates the state information needed
 * for the various rendering operations that Java supports.  This
 * state information includes:
 * <ul>
 * <li>The Component to draw on
 * <li>A translation origin for rendering and clipping coordinates
 * <li>The current clip
 * <li>The current color
 * <li>The current font
 * <li>The current logical pixel operation function (XOR or Paint)
 * <li>The current XOR alternation color
 *     (see <a href="#setXORMode">setXORMode</a>)
 * </ul>
 * <p>
 * Coordinates are infinitely thin and lie between the pixels of the
 * output device.
 * Operations which draw the outline of a figure operate by traversing
 * along the infinitely thin path with a pixel-sized pen that hangs
 * down and to the right of the anchor point on the path.
 *
 * @author  Sami Shaio
 */

3.2  Commentaire des méthodes et des constructeurs

• @param qui spécifie les paramètres de la méthodes. (0 à n)
• @return qui spécifie le retour de la méthode. On ne le met pas pour les constructeurs et les méthodes qui ne retourne rien (void).
• @exception qui spécifie les exceptions qui sont lancées par la méthode.
• @see qui indique les autres classes ou les autres méthodes qui sont en relation avec cette méthode. 
  

Voici un exemple de commentaire: 

/**
* Draws as much of the specified image as is currently available
* with its northwest corner at the specified coordinate (x, y).
* This method will return immediately in all cases, even if the
* entire image has not yet been scaled, dithered and converted
* for the current output device.
* If the current output representation is not yet complete then
* the method will return false and the indicated {@link ImageObserver}
* object will be notified as the conversion process progresses.
*
* @param img       the image to be drawn
* @param x         the x-coordinate of the northwest corner of the
*                  destination rectangle in pixels
* @param y         the y-coordinate of the northwest corner of the
*                  destination rectangle in pixels
* @param observer  the image observer to be notified as more of the
*                  image is converted.  May be <code>null</code>
* @return          <code>true</code> if the image is completely
*                  loaded and was painted successfully;
*                  <code>false</code> otherwise.
* @exception       IOException  If an input or output exception occurred
* @see             Image
* @see             ImageObserver
*/
public abstract boolean drawImage(Image img, int x, int y,
                      ImageObserver observer) throws IOException;

3.3  Commentaire pour les variables de classe et d'instance

/**
* Commentaire pour la variable de classe qui s'étend
* sur plus qu'une ligne
*/
private static Object classVar2;

/** Commentaire de la variable d'instance sur une ligne. */
private Object instanceVar1;

4  Indentation

Si une instruction s'étend sur plus d'une ligne, coupez-la selon les règles générales suivantes:

• Coupez après une virgule
• Coupez après un opérateur
• Favorisez la coupe d'une opération de haut niveau comparativement à une instruction de bas niveau.
• Alignez la nouvelle ligne avec le commencement de l'expression de même niveau sur la ligne précédente.
• Si les règles précédentes donnent un code peut lisible, car tout est collé dans la marge de droite, indentez de 8 espaces à la place. C'est-à-dire, qu'au lieu d'aligner la nouvelle ligne avec l'expression de même niveau, on remonte d'un niveau, mais en utilisant une indentation plus prononcée de 8 espaces.
  

Voici quelques exemples: 

someMethod(longExpression1, longExpression2, longExpression3,
           longExpression4, longExpression5);

var = someMethod1(longExpression1,
                  someMethod2(longExpression2,
                              longExpression3));

longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longname6;

/* On a utilisé une indentation de 8 espaces par rapport au niveau
supérieur, car tout serait trop collé vers la droite. */
private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother)
{
    ...
}

sinon on aurait eu:
private static synchronized horkingLongMethodName(int anArg,
                                                  Object
                                                  anotherArg,
                                                  String
                                                  yetAnotherArg,
                                                  Object
                                                  andStillAnother)
{
    ...
}

5  Déclarations

5.1  Nombre de déclaration par ligne

int level;
int size;

est préférable à

int level, size;

5.2  Initialisation

int rayon = 10;

est préférable à

int rayon;
... // Des lignes de code
rayon = 10;

5.3  Placement

void myMethod()
{
    int int1 = 0;   // Au commencement du bloc de la méthode

    if (condition)
    {
        int int2 = 0;     // Au commencement du bloc if
        ...
    }
}

Il y a une exception à cette règle et c'est pour les boucles for
où la variable compteur doit être déclarée à l'intérieur de
l'instruction.

for (int i = 0; i < max; i++)
{
    ...
}

5.4  Déclarations des classes (ou interfaces) et des méthodes

• Il n'y a pas d'espace entre le nom de la méthode et la parenthèse ouvrante pour ses paramètres.
• L'accolade ouvrante est sur la ligne suivante avec la même indentation que le début de la déclaration de la classe ou de la méthode. Sur cette ligne, il n'y a que l'accolade.
• L'accolade fermante commence la ligne suivant le bloc de code avec la même indentation que le début de la déclaration de la classe ou de la méthode.
• Pour les méthodes vides, les accolades sont sur la même ligne que la déclaration.
• Les méthodes sont séparées par une ligne blanche. 
  

Voici un exemple de déclaration de classe:

class Sample extends Object
{
    int ivar1;
    int ivar2;

    Sample(int i, int j)
    {
        ivar1 = i;
        ivar2 = j;
    }

    int emptyMethod() {}
}

6  Les énoncés

6.1  Énoncés simples

argv++;  // OK
argc--;  // OK
argv++; argc--; // Éviter

6.2  Énoncés avec accolades

• Le code à l'intérieur des accolades doit être indenté à un niveau de plus que l'énoncé.
• L'accolade ouvrante est sur la ligne suivante avec la même indentation que le début de l'énoncé. Sur cette ligne, il n'y a que l'accolade.
• L'accolade fermante commence la ligne suivant le bloc de code avec la même indentation que le début de la déclaration.
• Les accolades sont utilisées tout le temps, même quand il n'y a qu'une ligne de code à l'intérieur. De cette façon, il est plus facile d'ajouter des lignes de codes si nécessaire. 
  

6.3  Énoncés if, if-else, if elseif else

if (condition)
{
    énoncés;
}

if (condition)
{
    énoncés;
}
else
{
    énoncés;
}

if (condition)
{
    énoncés;
}
else if (condition)
{
    énoncés;
}
else
{
    énoncés;
}

Note: Les énoncés if utilisent toujours les accolades.

//Éviter cela
if (condition)
    énoncés;

6.4  Énoncé for

for (initialisation; condition; incrément)
{
    énoncé;
}

6.5  Énoncé while

while (condition)
{
    énoncés;
}

6.6  Énoncé do-while

do
{
    énoncés;
}
while (condition);

6.7  Énoncé switch

switch (condition)
{
    case ABC:
        énoncés;
        break;

    case DEF:
        énoncés;
        break;

    default:        //Obligatoire
        énoncés;
        break;
}

6.8  Énoncé try-catch

try
{
    énoncés;
}
catch (ExceptionClass e)
{
    énoncés;
}

Un énoncé try-catch peut être suivi d'un finally qui est toujours
exécuté, que le bloc try soit réussi ou non.

try
{
    énoncés;
}
catch (ExceptionClass e)
{
    énoncés;
}
finally
{
    énoncés;
}

7  Quelques règles de programmation

• Toujours suivre les normes.
• Si vous devez absolument contourner une norme, il faut la documenter dans le code. C'est-à-dire qu'il faut expliquer pourquoi vous ne respectez pas la norme dans cette situation.
• Ne jamais utiliser de nombres magiques dans le code. Il est préférable de se définir des constantes.
• Toujours déclarer les attributs d'une classe private. Pour y accéder, vous fournissez des méthodes get et set, si nécessaire.