• 1

Réussir un projet - Nommage

Note utilisateur:  / 2
MauvaisTrès bien 

Seconde partie de notre dossier sur la réussite d'un projet : Nous présentons l'intérêt des noms des éléments d'un projet.

Construire des noms pour améliorer ses développements WinDev

La réalisation d’un projet avec l’EDI WinDev, WinDev Mobile ou WebDev consiste en la création d’un nombre important de fichiers dont la compilation produira sa version utilisable par l’utilisateur final. Les classes, procédures, fonctions et variables composent à leur tour le code contenu dans ces fichiers. Enfin, les fichiers de données, relations et rubriques composent la structure des données utilisée par le projet.

Le développeur doit en permanence être en mesure de trouver le plus rapidement possible une portion de code ou une description de données. C’est dans ce but que nous avons très tôt proposé des règles de nommage pour les projets WinDev que nous allons revoir dans ce dossier. Ces règles régissent la construction du nom des fichiers du projet mais aussi des portions de codes et variables. Une pratique rigoureuse de ces règles permet de rendre compréhensible par son nom le contenu de tel fichier du projet ou de telle portion de code aux autres membres d’une équipe. Le premier avantage des règles de nommage pour l’équipe: comprendre la production de ses membres.

Depuis WinDev 9, l’éditeur de code de WinDev s’est vu implémenter la fonctionnalité de complétion de code. Celle-ci permet à l’éditeur de code de compléter les saisies en cours en proposant une liste. Etant disponible sur les éléments du projet et les variables, c’est le second avantage des règles de nommagepour le développeur : optimiser la saisie du code en profiter au maximum de la complétion. Le gain est alors une réduction drastique des erreurs de saisie.

Le troisième avantage des règles de nommage étant indirect, nous le traiterons plus tard dans le dossier…

Les éléments suivants sont une proposition qu’il faudra adapter à vos besoins.

Schéma général de nommage

L’objectif est simple : obtenir les informations de manière groupée par leur dénominateur de sens commun lorsqu’elles sont présentées en liste.

Les listes sont triées sur l’ordre défini par l’encodage de la page de caractère utilisée. Dans notre exemple, nous utilisons le WLangage en Français sur des machines en page de code ISO 8859-1 ou latin-1. Les listes y sont donc triées par ordre alphabétique. Les noms sont généralement des abréviations accolées. Or, la syntaxe naturelle française conduit à une lisibilité faible des listes de ces variables quand elles sont en ordre alphabétique. Prenons un exemple :

Pour des variables concernant un client et un fournisseur on écrit naturellement :

NomClient, PrenomClient, NomFournisseur, PrenomFournisseur ...

Liste correspondante triée sur l'ordre alphabétique :

NomClient, NomFournisseur, PrenomClient, PrenomFournisseur...

Cet ordre n'est pas utilisable naturellement. En effet, on peut voir des ensembles 'nom' et 'prénom' mais l'intérêt c'est d'obtenir les informations 'client' séparées des informations 'fournisseur'. Ainsi la construction suivante basée sur la syntaxe anglo-saxonne est plus facile à exploiter :

[ ClientNom, ClientPrenom ], [FournisseurNom, FounisseurPrenom ]...

On en déduit un schéma pour composer les noms à partir de leurs composantes de sens :

<Général><DétailMinimum>…<DétailMaximum>

Général
Abréviation indiquant le groupe de sens le plus général du nom
DétailMinimum
Abréviation indiquant le groupe de sens du niveau le moins détaillé du nom
DétailMaximum
Abréviation indiquant le groupe de sens du niveau le plus détaillé du nom

Un nom est donc composé des parties de sens allant du plus général au plus détaillé. On groupe les éléments définissant une même notion en utilisant une même base générale. On spécifie la notion en ajoutant des parties après le nom de base.

Chaque partie est accolée à la précédente. Elle commence par une majuscule et est libellée en minuscule.

Le nom d’une notion doit être choisi depuis le programme et non depuis un choix développeur qui sera subjectif et donc peu pérenne dans le temps. Il est important d’observer que l’EDI utilise ces règles pour produire des noms à la syntaxe particulière mais efficace, lui conférant cette grande facilité d’assimilation. En respectant ce schéma, vos équipes seront aussi en mesure de produire des programmes faciles à assimiler et donc à maintenir.

Charte de nommage

Depuis WinDev 10, L’EDI intègre en natif une charte de programmation. Elle permet une automatisation partielle de la construction des noms par l’affectation de préfixes aux éléments du projet. L’intérêt de ces préfixes est de grouper les éléments de même nature entre eux.

On trouvera ainsi la liste des préfixes de la charte naturellement organisés par détail croissant de leur usage dans le projet :

  • Elément du projet : nom des fichiers créés dans le projet
  • Champs de fenêtre/page et état : nom des champs affiché par le projet
  • Type des variables : type des variables dans le code du projet
  • Portée des variables : portée des variables dans le code du projet

Nous préconisons l’usage des majuscules pour les préfixes des éléments de projet et champs suivit d’un « _ ». Dans la mesure du possible toujours utiliser le même nombre de caractère (3). Pour les portées, une unique lettre en minuscule. Pour les types qui se trouveront accolés aux portées, l’usage de trois ou quatre minuscules suivies d’un « _ » est recommandé.

Eléments de projet et champs

Pour les éléments de projet et les champs de fenêtres / pages ou états, la charte vous permet d’affecter automatiquement un préfixe selon le type de l’élément. Nous vous invitons à le faire suivre du nom du fichier (entité du MCD) principal géré par l’élément suivi d’un ou des suffixes qui en spécifient le sens.

<PREFIXE_><ENTITE_>…<Suffixes>

PREFIXE_
Abréviation du type d’élément / de champ
ENTITE_
Abréviation du nom du fichier associé (MCD) ou de la fonction gérée
Suffixes
Abréviation du détail géré avec parties accolées.

Procédures et Variables

Pour les variables, la charte construit un préfixe en accolant la portée suivie du type de variable. Le nombre de portée permet de les coder sur un unique caractère, les types pouvant alors être codés sur trois ou quatre positions. Faire suivre les types par un « _ » permet de faciliter sensiblement la lisibilité du code. En effet la coloration syntaxique de l’éditeur de code affecte au préfixe ainsi construit une couleur plus claire si la charte est appliquée, mettant alors en évidence tant une erreur de préfixe que le nom de la variable.

<portée> <type_> <Général> <Détail>…

portée
Abréviation de la portée de la variable
type_
Abréviation du type de la variable
Général
Abréviation indiquant le groupe de sens du niveau le moins détaillé du nom
Détail
Abréviation indiquant un groupe de sens de niveau le plus détaillé du nom

Mise en place

WDForge vous propose en téléchargement une charte générique. Il vous appartient cependant de définir vos propres préfixes.

Une fois la charte définie pour vos projets, il vous suffit de l’ajouter dans leur description. Utiliser un espace partagé pour cet élément afin de ne pas démultiplier le fichier.

Enfin, il vous reste à activer le préfixage automatique en activant l’utilisation de la charte par votre projet. Une fois fait, vous pourrez au choix taper directement le nom de l’élément ou son préfixe suivit de son nom.

Note : L’utilisation du préfixage automatique implique une adaptation dans la saisie du code. En effet l’automatisme ajoute les préfixes uniquement quand on valide la saisie de la ligne de code suivant par ENTREE. L’adaptation consiste, en modification de ligne à se placer en fin de ligne avant de faire ENTREE pour que le préfixage ait lieu.

Aller plus loin…

Le respect du schéma de nommage, l’implémentation de la charte de programmation accompagnée de son intégration permettent donc de grandement améliorer la structuration des éléments produits. Les noms des éléments du projet et le code sont maintenant compréhensibles et se rangent naturellement dans des listes.

Pour autant le tableau n’est pas complet… nous allons donc ajouter quelques éléments.

Les constantes

Les constantes WinDev ont un statut spécial, elles peuvent être définies dans un fichier dédié (extension .WL) ou dans le code. Elément de code de statut spécial, nous proposons d’utiliser des majuscules pour les différencier des variables.

Leurs portées étant connues, leur type étant laissé à la discrétion du compilateur (chaines interprétées), il n’y a pas à proprement parler de préfixe qui convienne. Nous proposons alors de ne pas en donner et donc de commencer leur nom directement par un « _ » suivi de l’abréviation de l’élément qui les définit puis de leurs détails.

_<CONTENEUR_><Général> <Détail>…

CONTENEUR
Abréviation de l’élément qui décrit la constante
GENERAL
Abréviation indiquant le groupe de sens du niveau le moins détaillé du nom
DETAIL
Abréviation indiquant un groupe de sens de niveau le plus détaillé du nom

Analyse : fichiers et rubriques

Une fois que les noms des éléments de projet et le code sont normalisés, il reste un endroit où le nom requiert une attention particulière, c’est l’analyse. L’analyse contient la description des fichiers et des rubriques qui seront utilisés dans tous vos programmes qui mémorisent des informations : précisément le type principal de projets que l’on réalise avec l’EDI WinDev. Les programmes WinDev font un appel permanent aux fichiers et rubriques. Les trouver facilement est donc très important.

Fichiers

Les fichiers doivent strictement suivre le schéma général de nommage. Il est capital de les grouper par notion connexes du point de vue du programme. Par exemple on utilisera COMMANDE_LIGNE au lieu de LIGNE_COMMANDE pour que les lignes soient rattachées aux entêtes y compris dans les listes…

Nous ajoutons au nom un complément d’information important à prévoir dans la définition des fichiers :

  • Tous les fichiers doivent comporter une clé unique (Identifiant automatique) qui permet un positionnement précis quand on manipule les contextes fichiers
  • Les noms des fichiers sont donnés en majuscule pour les dissocier des variables
  • Tous les fichiers de l’analyse doivent comporter une abréviation que l’on peut affecter dans l’onglet détail de leur description. Ces abréviations sont utilisées dans les noms des rubriques.

<GENERAL_><DETAILMIN>…<DETAILMAX>(+ IDAuto + abréviation)

GENERAL_
Abréviation indiquant le groupe de sens le plus général du nom
DETAILMIN
Abréviation indiquant le groupe de sens du niveau le moins détaillé du nom
DETAILMAX
Abréviation indiquant le groupe de sens du niveau le plus détaillé du nom
IDAuto
Le fichier doit comporter un identifiant automatique
Abréviation
Le fichier doit comporter une abréviation

Rubriques

Les rubriques doivent strictement suivre le schéma général de nommage et particulièrement pour le choix relatif au sens avec les ajouts suivants :

  • Nous ajoutons et recommandons l’ajout en préfixe, de l’abréviation du fichier auquel appartient la rubrique.
  • On utilisera des noms génériques pour les notions qui définissent des données génériques : CODE pour les codes, LIBELLE pour les libellés…

Ainsi, dans tous les cas, le nom de la rubrique indique directement non seulement le nom de la rubrique mais aussi le fichier concerné. Cet ajout permet de distinguer toutes les rubriques du dictionnaire des données accessibles dans l’éditeur d’analyse (Liste des rubriques).

<ABREV_><GENERAL><DETAIL>

ABREV_
Abréviation du fichier contenant la rubrique
GENERAL
Abréviation indiquant le groupe de sens le plus général du nom
DETAIL
Abréviation indiquant le groupe de sens du niveau le moins détaillé du nom

Par exemple, le numéro d’une ligne de commande : COMMANDE_LIGNE.CL_LIGNENUMERO

Rubriques clés importées

La construction de relations dans le modèle de donnée permet de créer des rubriques clés importées. Ce sont les rubriques sur lesquelles vont s’effectuer les liens dans les fichiers liés. Nous recommandons de joindre l’abréviation du fichier lié au nom de la rubrique pour connaitre la provenance de la clé. La suite du nom étant alors conservée.

<ABREV_> <ABREVLIE_><GENERAL><DETAIL>

ABREV_
Abréviation du fichier contenant la rubrique
ABREVLIE_
Abréviation du fichier source de la liaison
GENERAL
Abréviation indiquant le groupe de sens le plus général du nom
DETAIL
Abréviation indiquant le groupe de sens du niveau le moins détaillé du nom

Au cours de la création de la liaison dans l’éditeur d’analyse, il suffit d’ajouter l’abréviation du fichier cible en préfixe quand la rubrique est importée dans le fichier lié. Celle du fichier d’origine étant alors reportée par copie naturelle du nom de la rubrique.

Rubriques clés composées

Les clés composées sont construites à partir d’autres rubriques du fichier. Elles n’ont pas de signification intrinsèque. Nous recommandons donc que leur nom soit une indication de leur structure.

<ABREV_> <CLE_> <ABREV1><ABREV2>…

ABREV_
Abréviation du fichier contenant la rubrique
CLE_
Indicateur qu’il s’agit d’une clé composée
ABREV1
Abréviation de la rubrique 1 (2 caractères)
ABREV2
Abréviation de la rubrique 2 (2 caractères)

Aller plus loin encore : le troisième avantage des règles de nommage

WinDev propose des fonctions qui permettent au programme d’énumérer les composantes du projet. Par ailleurs, il est possible, toujours par programmation, d’utiliser ces composantes à partir de leur nom construit par programmation dans une chaine : c’est l’indirection. Une construction rigoureuse des noms des éléments d’un projet, ajoutée à l’énumération et l’indirection permet donc de construire des programmes capables de tenir compte de leur structure même. Le développeur peut ainsi gagner en compacité de code à produire : la même fonction s’appliquant sur un ensemble homogène d’information. C’est le troisième avantage des règles de nommagepour le développeur : gagner en compacité du code généré.

Une première illustration de ce type de programmation est le code contenu par les fenêtres RAD qui permettent des actions génériques sur les fichiers associés aux fenêtres. Une seconde illustration pourrait être un outil de construction de requête qui ne connait pas à priori les fichiers utilisés.

En conclusion, un respect rigoureux des règles de nommage couplé avec les énumérations et l’indirection permettent de produire des portions de projet qui en manipulent des éléments sans y être directement lié. Celles-ci sont donc portables à tous les projets respectant cette règle, produisant alors une importante économie de code produit.

image image