Réussir un projet - Nommage

• 

Note utilisateur:  / 8

Détails

Publié le lundi 25 mai 2015 16:19

Écrit par R_B

Affichages : 6345

---

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.

Réussir un projet - Documenter

• 

Note utilisateur:  / 6

Détails

Publié le lundi 25 mai 2015 15:10

Écrit par R_B

Affichages : 5619

---

Première partie de notre dossier sur la réussite d'un projet : Nous abordons l'intérêt de la documentation d'un projet.

Documenter

La documentation projet au service du développement WinDev

La réalisation d’un projet est souvent assimilée aux seules tâches de développement. C’est malheureusement omettre l’importance de la réalisation de la documentation. L’intérêt de la documentation est de faciliter la communication non seulement au sein de l’équipe de développement mais aussi entre cette équipe et son environnement. Il s’agit alors généralement des autres services de l’entreprise. Ils pourront utiliser cette documentation pour consulter les détails du projet. Elle sert aussi de départ à la réalisation des manuels d’utilisation des fonctionnalités. La documentation d’un projet peut être répartie en trois parties.

La documentation d’analyse

La documentation d’analyse regroupe l’analyse fonctionnelle qui peut être réalisée au moyen de méthodes diverses (APTE, UML…). Elle traite de l’étude du besoin qui est alors modélisée jusqu’à proposer des solutions fonctionnelles. La méthode APTE place dans un premier temps la solution dans son environnement pour étudier ses relations avec ce dernier et énoncer les fonctions de service et fonctions contraintes : C’est l’analyse fonctionnelle externe. La reprise de chacune d’elle cette fois-ci au sein du projet permet d’énoncer les fonctions techniques et de déterminer les solutions techniques : c’est l’analyse fonctionnelle interne. Il est possible de modéliser détail de cette analyse par des diagrammes FAST, SADT, ou des matrices RACI pour une approche d’analyse par la répartition des tâches.

Pour la réalisation d’un projet de gestion informatique les solutions technique sont des traitements, les solutions techniques regroupent alors les données saisies et produites. Chacune des fonctions créées au cours de ces étapes d’analyse est validée dans la durée de vie du projet. Il s’agit d’indiquer les raisons de leur existence et pour chaque raison de déterminer ce qui est susceptible de les faire disparaitre afin de vérifier qu’elles satisfassent le besoin pour toute cette durée.

De même chacune de ces fonctions est caractérisée. On apprécie alors la manière donc la fonction est remplie ou la contrainte respectée. Concrètement on trouvera ici les valeurs limites acceptées. La documentation d’analyse sert de base de travail pour analyser un besoin et préparer le travail du développeur. Elle permet aussi d’assurer la présentation du projet sous forme de cahier des charges dont le chiffrement permet la réalisation des devis et la planification la production.

Dans un projet WinDev, on trouvera cette gestion dans le Centre de Suivi de projet. Chaque fonction technique donnant alors lieu à une « Exigence ». Il est alors possible de décrire l’exigence et surtout de faire référence au document qui la décrit. Les exigences sont alors découpées en « tâches » de développement, documentation et tests. Les solutions techniques étant alors mises en place dans le modèle de donnée du projet ou « analyse ». La gestion de la production consiste alors à affecter les tâches aux membres de l’équipe en donnant des estimations de durée. Cela permet de remplir leur planning et d’assurer leur suivi. Il est possible de hiérarchiser les tâches et donc de produire un diagramme de GUANT.

On l’aura compris la documentation d’analyse est réalisée par le chef de projet et permet de partir d’un besoin exprimé par le client pour arriver aux tâches de développement.

La documentation de développement

Rédigée par les développeurs, la documentation de développement indique la manière dont la fonction d’analyse est réalisée. Elle organise les éléments de projet mis en œuvre et indique leurs rôles respectifs. Elle description et donne les résultats des tests produits.

Elle peut aussi indiquer les solutions envisagées mais abandonnées en précisant la raison de ces décisions. Ainsi, lors d’une évolution de la solution, il sera possible de tenir compte de ces études selon la validité des raisons invoquées.

La documentation de développement est le moyen pour le développeur de communiquer sur sa réalisation à tout autre interlocuteur qui n’a accès au code tels que : chef de projet, service qualité ou marketing… C’est un outil de communication interne souvent laissé de côté par manque de temps. Cependant, si sur une durée plus longue, le développeur du code n’est plus présent, cette documentation est nettement plus efficace qu’une rétro-analyse de son travail.

La documentation du code

Rédigée par les développeurs au sein des programmes, la documentation du code décrit son prototypage paramétrique et le fonctionnement.

L’éditeur de code WinDev permet de formater les commentaires d’entête des procédures et fonctions. Accès : Menu > Outils > Options > Options de l’éditeur de code, volet « Doc. ». Cocher les zones que vous souhaitez que le développeur remplisse.

Ces paramètres seront alors utilisés pour la construction du squelette de commentaire à chaque modification de la déclaration de procédure. En cochant, « Synchroniser les commentaires avec la syntaxe des procédures », les modifications du commentaire suivront la réalité de la syntaxe.

L’avantage de cette documentation est que l’éditeur de code propose lors de la saisie d’un appel à la procédure, en plus de la complétion des paramètres, l’affichage en barre de message de leur description saisie dans ces commentaires.

Ensuite, il est recommandé, même si on utilise les règles de nommage, de préciser le rôle des variables déclarées en début de procédure.

Enfin, au sein des procédures, il est utile de commenter les blocs de codes enroulables afin de conserver une lisibilité de l’algorithme même avec le code enroulé.

Il est possible de fixer un quota de commentaire aux développeurs dans les règles de gestion du projet via la politique de réintégration dans le GDS.

La documentation de code est à destination de son lecteur et doit l’aider à comprendre le cheminement de l’exécution.