May 18, 2014 11:46:22 PM lutece lutece avatar   553    

Règles de nommage


Toutes les règles de nommage décrites ici doivent être vérifiées à l’aide des outils Checkstyle et PMD. Ces outils doivent être configurés de façon à supporter les règles de nommage spécifiques, en utilisant les fichiers de configuration fournis par le projet Lutece.

Principes généraux

Les noms des identificateurs doivent respecter les règles suivantes:

  • Etre des noms communément utilisés pour désigner l’objet
  • Ne pas introduire de contresens ou de problème d’interprétation
  • Etre en langue anglaise
  • Ne jamais être tronqués ou contractés

Ne pas utiliser les constantes ou les variables pour stocker des messages d’erreurs en dur (utilisation des fichiers properties dédiés). En règle général éviter toute valeur en dur, utiliser au maximum les fichiers de propriétés .properties de l’application ou des plugins.

Ne pas utiliser de chemins absolus (les seuls chemins absolus utilisés sont stockés dans les paramètres existant du fichier config.properties).

Variables

Les types de base de Java doivent avoir les préfixes suivants:

PréfixeType
nint
strString
bboolean
llong

Les instances d'objet doivent être préfixées par le nom de la classe ou la partie représentative du nom de la classe indiquant le plus précisément possible le type d'objet .

ClasseExemple d’instance de la classe
HtmlTemplatetList
StringBuffersbXml
DatedateBegin
List, ArrayListlistUsers

Mise en forme : Notation Hongroise à l'exception de l'initiale en minuscules, pas d'underscore. Les abréviations sont à éviter.

Les variables d’instance (static ou non) doivent être préfixées par un underscore.

Constantes

Toute valeur littérale de chaîne de caractères ou numérique doit être placée dans une constante . Les déclarations des constantes doivent être faites dans les premières lignes du source ou dans une classe spéciale dédiée aux constantes.

Les préfixes doivent indiquer la nature de la constante.

Les préfixes courants sont :

PréfixeType
ACTION_Pour une action du modèle MVC
DSKEY_Pour les clés du Datastore
JSP_URL_pour les url des JSP
MARK_Pour les noms des signets à substituer dans les templates
MESSAGE_Pour les messages ou les clés de message utilisées par Message.jsp
PARAMETER_pour le nom d’un paramètre de la requête HTTP
PATH_Pour les chemins des répertoires
PROPERTY_Pour les noms de clé d'un fichier .properties
TEMPLATE_Pour les noms des templates HTML
VIEW_Pour une view du modèle MVC

Mise en forme des constantes : tout en majuscules, mots séparés par des underscores.

Pour un plugin d'une certaine taille, les constantes pourront être regroupées dans une classe fr.paris.lutece.plugins.myplugins.web.Constants .

Objets de base de données

Tous les noms de table et de colonne doivent être en minuscules en séparant les mots par des underscores. Tous les noms de table doivent être préfixés par nom du plugin_ à l'exception des tables du noyau qui sont préfixées par core_.

Les requêtes SQL

Les requêtes SQL des classes DAO (couche métier) doivent être placées dans des variables de type string et doivent respecter la forme suivante:

  • mots clés en majuscules (SELECT, UPDATE, WHERE , AND …),
  • noms des colonnes en minuscules,
  • alias des noms de colonnes sous forme de lettres de l’alphabet

Exemple de syntaxe:

String strSQL = SELECT a.id_theme, a.description_theme FROM theme a, theme_newsletter b WHERE a.id_theme = b.id_theme and b.id_newsletter = ? ;

Fichiers templates

Extension : .html

Mise en forme : tout en minuscules, mots séparés par des underscores, pas d’utilisation de tirets, langue anglaise, pas d’abréviations.

Règles de nommage pour les fichiers servant à un traitement standard:

  • create_fonctionnalité.html pour l’affichage d’une page de création,
  • modify_fonctionnalité.html pour une page de modification,
  • remove_fonctionnalité.html pour une page permettant une suppression,
  • manage_fonctionnalité.html pour l’affichage d’une page de gestion d’une fonctionnalité,
  • view_fonctionnalité.html pour une page d’affichage d’une fiche, confirm_fonctionnalité.html pour une page de message de confirmation,
  • fonctionnalité_list.html pour une page d’affichage d’une liste.
  • fonctionnalité_row.html pour l’affichage d'une ligne d’une liste.

Règle de nommage des signets servant à la substitution des valeurs des Bookmarks: langue anglaise, minuscules, mots séparés par des underscores, pas d’abréviation ni de tirets. (ex: $ {file_name} )

Fichiers JSP

Mise en forme : Notation Hongroise, langue anglaise, pas d’abréviation, pas de tirets,pas d'underscore;

Règles de nommages pour les fichiers servant à un traitement d’affichage standard:

  • CreateFonctionnalité.jsp pour les pages servant à un traitement d’affichage de page de création,
  • ModifyFonctionnalité.jsp pour les pages servant à un traitement d’affichage de page de modification ,
  • RemoveFonctionnalité.jsp pour les pages servant à un traitement d’affichage de page de suppression,
  • ManageFonctionnalité.jsp pour les pages servant à un traitement d’affichage de page de gestion,
  • ViewFonctionnalité.jsp pour les pages servant à un traitement d’affichage de page de la fiche de la fonctionnalité,
  • ConfirmFonctionnalité.jsp pour les pages servant à un traitement d’affichage de la page de confirmation ,
  • Fonctionnalité List.jsp pour les pages servant un traitement d’affichage de liste.

Mêmes règles de nommage pour les Jsp de traitements sans affichage, auxquelles s’ajoute le préfixe Do (ex: DoCreateFonctionnalité.jsp , DoModifyFonctionnalité.jsp … )

Fichiers images

Règle de nommage: langue anglaise, utilisation de minuscule et d’underscores entre les mots, pas de tirets ni d’abréviation. Les préfixes utilisés doivent correspondre à la fonction de l’image quand elle existe:

PréfixeType
b_Images servant de bouton
i_Images servant d icône (ex : i_delete.png)
l_Images d’une ligne

Le format des images servant à la présentation des pages doivent être au format .png.

Fichiers XML

Les balises XML utilisées dans l’application devront être en minuscules, séparés par des tirets lorsqu’il s’agit de mots composés, en langue anglaise, sans abréviations.

Les noms des balises devront être le plus proche possible du modèle qu’ils doivent représenter: par exemple «portlet-id» pour la balise stockant la valeur de l’identifiant du portlet récupéré dans la colonne id_portlet de la table portlet.