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éfixe | Type |
|---|---|
| n | int |
| str | String |
| b | boolean |
| l | long |
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 .
| Classe | Exemple d’instance de la classe |
|---|---|
| HtmlTemplate | tList |
| StringBuffer | sbXml |
| Date | dateBegin |
| List, ArrayList | listUsers |
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éfixe | Type |
|---|---|
| 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éfixe | Type |
|---|---|
| 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.