Conventions de codage

Suivi et gestion de la documentation

Validation du document

 

Nom

Date

Signature

Rédacteur

Stéphane Bouchet

20/04/2006

  

Approbateurs

      

Récapitulatif des changements

Opération

Version

Date

Description

Création

1.0

11/07/2003

  

Ajout des règles de codages

2.0

07/07/2004

  

passage html

2.1

1/10/2005

  
Mise à jour
 3.0 20/04/2006 Ajout de l'utilisation des fichiers de config Eclipse.
Ajout de "bonnes pratiques".

 Liste de diffusion

Pour validation / information
   
   
 

Généralités

Ce document décrit une liste de conventions de codage requise pour le projet CASTORE. Ces conventions de codages reprennent celles établies par SUN (voir document annexe, Official Sun Java Coding Conventions ). Si des conventions ne sont pas reprises ici, celles de Sun s'appliquent par défaut.

Tout le codage et le nommage doit se faire en langue française autant que possible.

1.Nommage

1.Packages

Le projet CASTORE étant découpé en modules et en projets , il existe une grande quantité de packages. Tout les modules sont des sous packages de fr.emn.castor . Les packages doivent suivre la structure suivante : 

      fr.emn.castor.<NomDuModule>.<ComposantDuModule> s'il s'agit des nouveaux modules dans le 'Core'

Sinon le package doit contenir l'information du projet auquel il appartient : applets, servlets, ... voir les différents projets.

Le nommage des packages doit suivre les spécifications de Sun (Chapitre 9).

Le terme ComposantDuModule est laissé libre au développeur. Les noms des packages suivants sont par contre obligatoires : 

fr.emn.castor.<NomDuModule>.metier
 Contient la logique métier du module

2.Classes et Interfaces

Pour les interfaces, faire précéder le nom par un i majuscule « I » .

            Exemple : IIndexation, IUtilisateur...

Pour les classes Abstraites, faire précéder le nom par un A majuscule, ou par le mot "Abstract".

            Exemple : ATrans, AbstractEngine...

Pour les exceptions faire suivre le nom par " Exception " .

            Exemple : WorkflowException

3.Méthodes

Pour les méthodes de type 'getter – setter', la convention est la suivante :

<> getter : getX()
<>setter : setX()

prédicats :

isX() ou containsX()

4.Variables et Constantes

Par défaut s'applique les conventions de Sun (Chapitre 9) .

2.Codage

1.Parenthèses

Pas de nouvelle ligne pour l'ouverture de parenthèses. Les parenthèses fermantes se font sur une nouvelle ligne. Exemple :

if (size < currentSize) {
	size = inStream.available();
	} catch (IOException e) {
	}
} else if (size == currentSize) {
	++size;
} else {
	--size;
}

Toujours des parenthèses pour les expressions if sur une seule ligne :

 if (log.isDebugEnabled()) {
       log.debug("logging..."); 
}

2.Espaces et Indentations

Pas de tabulations. 4 espaces. Ceci pour éviter des conflits entre éditeurs de code.

Les opérateurs doivent être entourés par des espaces : 

      a += c + d;

3.Commentaires

Les commentaires JavaDoc doivent exister pour toutes les variables, les méthodes, mêmes privées.

4. Bonnes Pratiques

D'une manière générale, tout le code métier de chaque module est "caché" dérrière une facade. Le package contenant la facade contient aussi une classe gérant les constantes utilisées par la facade, et une classe d'exception.
Les facades doivent utiliser des types simples comme parametre et comme type de retour. Les générics java 1.5 sont autorisés si ils contiennent des types simples.
Ces types simples sont :
Il est d'usage de déléguer toutes les méthodes de la facade vers des classes métier. Ainsi, le code d'une méthode de la facade doit etre court (pas plus de 5 lignes). Si ce n'est pas le cas, modifiez le code en conséquence.

 5. Utilisation du common-logging

Ne pas utiliser de System.out. Utiliser le système de log inclus avec le projet : 

private static Log
log = LogFactory.getLog(MyClass.class);
public void someMethod()
{     
	if (log.isDebugEnabled()) {
	log.debug("some debug text");
	}
}

Ne pas utiliser de log lorsque la classe est persistante !

Il ne doit pas y avoir d'utilisation de logging dans la facade. Par contre il est obligatoire d'utiliser le commons-logging pour tout le reste de l'application.

2.Imports

Utiliser les noms de classe complet. Pas de « * ».

3.Constructeurs

Toujours implémenter le constructeur par défaut. Si celui-ci ne doit pas être utilisé, changez sa visibilité en private.

3.Utilisation dans l'environnement Eclipse

1.Les outils par défaut

Il existe des outils pour formater le code source disponibles par défaut dans Eclipse. Pour les utiliser il suffit de faire un clic droit dans le code source d'une classe, puis « formater ». Le paramétrage du formatage se fait via le menu préférences. (Fenêtre/Préférences/Java/Module de formatage du code). Il suffit d'importer les conventions pour que celles-ci soient automatiquement appliquées lors du formatage du code.

Fichier de configuration du formatage sous Eclipse

Remarque : cet outil ne fait QUE du formatage de code (tabulations, parenthésage).

Un autre outil par défaut est l'utilisation des templates pour ajouter du code de façon automatique. De même que précédemment, il suffit d'importer ces templates pour que celles ci soient automatiquement appliquées. (création de nouveau fichier par ex. )

Fichier de Templates sous Eclipse

Enfin, il existe un troisième outil, permettant de regrouper les imports de façon automatique. 

Fichier de configuration des imports sous Eclipse

2.Les plugins

Il existe par ailleurs des plugins pour Eclipse qui permettent de faire de la vérification de style de codage. Celui que nous utiliserons est CheckStyle. Par défaut, celui-ci applique les conventions de codage de SUN à des applications JAVA. le fichier de configuration utilisé pour CASTORE se trouve a la racine du projet 'Maven', appelé castore_checks.xml.

Télécharger la dernière version  du plugin checkstyle