Planisware : focus sur les bonnes pratiques de nommage
Problématique
Lorsque l’on s’attache à mettre en œuvre des bonnes pratiques de nommage sous Planisware, 2 grandes familles d’objets sont à prendre en compte :
1. les objets d’environnement Planisware (formules nommées, tables, champs supplémentaires…)
2. les variables, fonctions et méthodes définies en script OJS
Le respect de normes dans le développement est fondamental, car il permet la maintenabilité du code au cours de la vide d’une application. Le non-respect de conventions pour le nommage des objets et l’écriture du code rendra les corrections et évolutions plus couteuses (en temps et en énergie) et augmentera les risques de régression (dus en général à une mauvaise compréhension du paramétrage).
1. Bonnes pratiques de nommage pour les objets Planisware
Afin d’identifier rapidement la nature des objets d’environnement Planisware, il est fortement recommandé d’utiliser une convention de nommage homogène. L’éditeur Planisware propose une convention assez simple et pratique. Elle est à ce jour communément appliquée dans la plupart des applications développées sous Planisware. D’ailleurs, elle est utilisée dans le paramétrage Processes standard.
De manière générale chaque objet aura un nom construit sur le modèle suivant :
<DESCRIPTION_COMPLEMENTAIRE>
Exemple : GPO_AA_B_TO_BE_DELETED
Ici on prend une application fictive appelée GPO (Gestion de Projets Opérationnelle). Il s’agit ici d’un objet de type champ supplémentaire (additional attribute) que l’on indiquera donc AA. La dernière partie permet de préciser :
→ le type de retour de l’objet (booléen, chaîne, nombre, durée ou date) lorsque c’est pertinent (pour une formule nommée ou un attribut supplémentaire)
→ des éléments de description permettant de comprendre rapidement le rôle de cet objet
<ID_APPLI_OU_CLIENT>
Cette partie du nom contient donc une abréviation permettant de savoir rapidement l’application dont il s’agit. Pour le paramétrage Planisware ce sera généralement l’abréviation du module auquel cet objet est rattaché : _PM, PORT etc…
Historiquement les principaux modules Planisware possédaient les abréviations suivantes :
→ IF: Infra
→ IT: Infra IT
→ IP: Infra Pharma
→ IS: Issue
→ AD: Admin
→ PM: Project Management
→ RM: Resource Management
→ PE: Parametric Estimation
→ SI: Simulation
→ PW: Project Wizard
→ CO: Collaboration
→ WT: WBS Type
→ ML: Multi-Level
→ PO: Porfolio
<TYPE_OBJET>
Cette partie est la plus formatée et la plus importante, car elle permet d’un seul coup d’œil de faire la différence par exemple entre une formule nommée (calculée) et un champ supplémentaire (stocké).
Voici la liste des principales abréviations communément utilisées dans la communauté des développeurs Planisware :
→ AA: Additional Attribute
→ AL: Alert
→ AT: Attribute Type
→ BS: Breakdown Structure
→ CC: Composite Curve
→ CF : Cost Field
→ ET: Expenditure Type
→ LO: Lock
→ MS: Macro sequence
→ MC: Manager for charts
→ MO: Multiple operation
→ NF: Named Formula
→ JS: OPX2 script macro
→ PS: Parameter Set
→ PT: Permanent Table
→ RA: Relation Attribute
→ RE: REport
→ SF: Symbolic Field
→ ST: STyle
→ SV: Simulation Variable
→ TA: Table Agregation
→ TT: Temporary Table
→ UM: Update Macro (et pas Unaccompanied Minors 😉)
Comme on peut le constater en général on préfère utiliser les termes en anglais pour éviter toute confusion. Cependant, certaines applications préfèrent appliquer des traductions en français. Par exemple NF (Named Formula) peut se transformer en FN (Formule nommée). Ce n’est pas une obligation, mais de par notre expérience, nous avons constaté que la version en anglais s’avère être plus simple et plus universelle.
<TYPE_RETOUR>
Comme indiqué précédemment, le type de retour n’est pas obligatoire dans la mesure où tous les objets n’en ont pas nécessairement.
Les objets suivants possèdent un type de retour :
→ Champ supplémentaire
→ Formule nommée
Voici la liste des principales abréviations de type de retour utilisées dans la communauté des développeurs Planisware :
→ N: number
→ S: string
→ B: boolean
→ D: date
→ U: duration
→ T: notepad
→ X: attribute type
Une fois encore, l’expérience a montré qu’il est plus compréhensible et universel, pour des développeurs, d’utiliser des abréviations en anglais. Il convient toutefois de faire attention au paramétrage de certaines applications dont le type sera indiqué en français ce qui peut être perturbant au premier abord (exemple C pour « Chaîne » au lieu de S).
<DESCRIPTION_COMPLEMENTAIRE>
C’est la partie la plus libre du nom, mais elle reste essentielle pour les développeurs. Il est en effet primordial de choisir une description sans ambigüité. Choisir un nom prêtant à confusion peut avoir deux effets :
→ Obliger un futur développeur à rentrer dans le détail de la définition technique de l’objet pour comprendre son utilisation
→ Faire un contre-sens complet sur l’utilisation de l’objet
En cas de doute, il peut être judicieux de demander l’avis externe d’un collègue.
Un débat se pose parfois sur la langue à utiliser pour cette description :
→ Doit-on utiliser l’anglais comme pour les autres parties du nom de nos objets ?
→ Ou est-il plus judicieux d’utiliser le français pour faciliter la compréhension fonctionnelle ?
La question se pose, car cette deuxième méthode permet d’éviter la traduction de termes métiers et acronymes très spécifiques. Le débat reste ouvert. Cependant, par expérience, nous avons constaté qu’il était souvent plus simple et plus pertinent de conserver un descriptif en français pour les applications françaises qui possèdent des concepts métier à la fois difficilement traduisibles en anglais et spécifiques à l’activité.
2. Conventions d’écriture du code Plansiware (OJS)
Sur ce point il n’existe à notre connaissance pas de recommandations officielles de l’éditeur sur ce sujet. Les conseils suivants sont issus de nos retours d’expérience.
2.1. En tête et commentaires
Le versionning du code contenu dans les scripts Planisware est essentiel. En effet, il permet de connaître avec précision le contenu du code exécuté dans l’application et de suivre le contenu des évolutions apportées.
Si vous n’avez pas d’en-tête à disposition, un bon point de départ peut être de reprendre un script du standard Processes pour s’inspirer de l’en-tête. Il est aussi tout à fait possible de vous baser sur des standards de votre entreprise. L’essentiel est d’avoir un suivi des versions.
Voici un exemple d’en-tête de script :
Exemple de script standard Planisware
Astuce : il est également possible d’ajouter une instruction « writeLn » indiquant le nom du script et la version à la fin du code. De cette manière, un simple coup d’œil dans les logs vous permettra de connaître la version du script évaluée au démarrage de l’application.
Exemple :
writeln(« Script GPO_JS_MON_SCRIPT.ojs loaded version $Revision: 1.03 $ »);
2.2. En-tête par fonction
Un en-tête (commentaire à la mode javadoc) peut être ajouté avant chaque fonction. Ces quelques lignes de commentaires permettent d’indiquer :
→ le rôle de la fonction
→ les arguments et leur type
→ le type de retour de la fonction
Cette manière de faire permet une meilleure maintenabilité du code OJS.
2.3. Nommage des variables
Le code OJS a pour caractéristique commune avec le JavaScript (dont il dérive) le fait que ses variables ne sont pas typées. Une même variable peut successivement contenir une date, une chaîne de caractère puis un booléen sans aucun cast (transtypage) préalable. Cette caractéristique peut être très puissante, mais, de par sa permissivité, nécessite de la méthode pour ne pas rapidement devenir difficile à lire et à maintenir.
Préfixer les variables (et respecter les types préfixés !) peut être une bonne méthode pour améliorer l’organisation et la lisibilité du code.
Voici une liste d’exemples de préfixes qu’il est possible d’utiliser :
→ o_ dans le cas d’un objet Planisware
→ v_ pour un vecteur (vector)
→ h_ pour une table de hachage (hashtable)
→ s_ dans le cas d’une chaîne de caractère (string)
→ n_ dans le cas d’un nombre (number)
→ b_ dans le cas d’un booléen (boolean)
→ d_ dans le cas d’une date (date)
→ x_ dans le cas d’une variable dont on ne connait pas encore le type (ce cas peut se présenter, notamment, lorsque l’on écrit des fonctions de type « reader » qui prennent des attributs en paramètre qui peuvent être de types différents)
Cependant, dans la mesure où l’éditeur ne donne pas encore de directives fermes à ce sujet, ces pratiques ne sont pas encore uniformisées. L’idéal est de se mettre d’accord sur les conventions adoptées en début de projet. Cependant, pour des projets n’ayant pas mis en œuvre ces pratiques dès le départ, il reste tout de même pertinent d’appliquer des conventions de nommage uniformes aux variables des fonctions modifiées. Cela permet de tendre petit à petit vers la cible en améliorant qualité et maintenabilité du code.
Pour ce qui est du reste du nom des variables, il n’y a pas de règle établie. Cependant, comme pour du code « classique », il doit être cohérent avec le rôle et le contenu de la variable.
2.4. Nommage des fonctions
Là non plus, il n’existe pas encore de règles fermes imposées par l’éditeur.
Cependant, en analysant le code standard Processes, on s’aperçoit que l’on retrouve la même règle de nommage que pour les objets d’environnement Planisware :
<ID_APPLI_OU_CLIENT>_JS_(<RETURN_TYPE>)_<DESCRIPTION_CMPLMNTAIRE>
Ici le type est fixé à JS pour JavaScript.
Selon nous, cette convention de nommage permet d’obtenir, d’un simple coup d’œil, les principales caractéristiques de la fonction. Cependant, si votre entreprise possède déjà sa propre convention ou utilise des codes métier spécifiques, il est tout à fait possible de les utiliser, la seule contrainte étant de respecter l’uniformité du nommage de l’ensemble des fonctions de l’application.
PS : Merci à Laurent pour sa relecture attentive !