Conventions de conception - florentdupont/Conventions GitHub Wiki

L'idée de ce document est de définir des conventions de conceptions. A ce niveau la conception apparait lors de la création de son modèle UML ou lors de la définition de concepts "fonctionnels" dans le code. Ces conventions sont des règles qui s'adaptent a beaucoup de langages. Dans le document ci dessous, on fait référence à une approche MDA dans laquelle, la conception est effectuée depuis un modèle (UML par exemple) et le code généré à partir de ce modèle. Les règles énoncées ici sont en conformités avec les conventions de codage.

1.Généralités

1.1Nommage des classes

Le nommage des classes dans le modèle doit rester le plus compréhensible possible. N'oubliez pas que le modèle a également une notion documentaire et qu'il sera partagé par vos collègues : il est plus compréhensible de lire une classe qui s'appelle ReferenceActivite plutôt qu'une classe qui s'appellera RFR_ACTVT ou encore RfrActvt.  

2.2 Commentaires

Ne pas hésiter à commenter le modèle. Dans une approche MDA, le code généré prend en compte ces commentaires. Les commentaires sont applicables sur plusieurs niveaux :

  • commentaires sur les classes;
  • commentaires sur les attributs;
  • commentaires sur les méthodes ;
  • commentaires sur les paramètres de méthodes.

Il est également recommandé d’apposer des commentaires sur les diagrammes si ceux-ci sont trop complexes pour être compris rapidement. Ces commentaires ne seront pas générés mais permettront de mieux appréhender la modélisation.

2. Organisation des diagrammes

Idéalement, un bon diagramme ne doit pas comporter plus d’une dizaine de classe. Avec plus de classes sur un diagramme celui-ci devient vite illisible.

Pour les diagrammes trop complexes, il est possible de faire apparaître plus de classes ou découper en plusieurs diagrammes, chacun présentant un point de vue différent.

Astuce
Si l'on souhaite afficher un diagramme avec un grand nombre de classes (par exemple, pour afficher la cinématique glabale d'un application notamment), il est possible de paramétrer l’affichage des classes pour ne pas faire apparaître les attributs ou les méthodes et ainsi alléger la visualisation.

Sur les diagrammes de Service
Les diagrammes vont se centrer sur les objets de la couche Service. Il est utile de montrer par qui ces objets sont appelés et quels autres objets ils vont appelés à leur tour.

3. Données métier

Nommez les objets pour que l'on puisse facilement savoir de quoi il s'agit d'un point de vue fonctionnel. RéférenceActivité : on sait de quoi ça cause. RefAct on ne sait plus trop... Si vous voulez que le code généré (souvent pour les scripts SQL) ait un autre nom, vous pouvez renseigner la propriété abbreviation = "ref_act" -> dans le code généré, vous aurez une table qui s'appellera ref_act.

Ce qu’il ne faut pas faire
Ref_ACT

Ce qu’il faut faire
ReferenceActivite

3.1 Nommage des attributs

Le nommage des attributs doit rester le plus compréhensible possible (référence plutôt que ref) il est préférable de suivre le nommage standard "à la Java", c'est à dire avec des noms d'attributs en minuscules, en évitant les caractères spéciaux (notamment « _ » qui est à réserver aux constantes). Exception : Ne pas hésiter à laisser les acronymes tels quels (tout en majuscule). (SNCF au lieu de sncf)

Ce qu’il ne faut pas faire

Ref   
Ref_INSEE

Ce qu’il faut faire

reference
referenceInsee

Il pourra également être possible d’utiliser la propriété "abréviation" pour générer un nom de colonne en base de données différent.

Concernant les termes de nommage, évitez de faire apparaître les articles.

Ce qu’il ne faut pas faire

numeroDeTrain
nombreDeClient

Ce qu’il faut faire

numeroTrain
nombreClients

3.2 Nommage des constantes

Les constantes sont en majuscules. Chaque mot est séparé par un « _ » (exemple : MA_CONSTANTE).

Ce qu’il ne faut pas faire

ma_constante
VALEURDEPI

Ce qu’il faut faire

CONSTANTE
VALEUR_DE_PI

Enumération

Il est préférable de les distinguer des Objets métiers et donc de les suffixer par « Enum » (par exemple GenreEnum).

Ce qu’il ne faut pas faire

TypeCivilite
Planete

Ce qu’il faut faire

CivilitéEnum
PlaneteEnum

Question : Faut il gérer les booléen en tant qu’Enumération ?
Il est préférable de ne pas représenter le type booléen en tant que Enum. Pourquoi ? Parce qu’il s’agit d’un type de données (qui ne peux représenter que 2 valeurs) et qu’il est préférable de le gérer autrement  en considérant que s’il n’est pas renseigné sur l’interface, on lui donne une valeur par défaut (faux étant le plus standard). D’un point de vue ergonomique, c’est probablement le meilleur des cas.
(Sur mon PC, le WiFi est soit activé, soit pas activé. Il n’est jamais dans un état non déterminé.)
Plus d’info ici : http://ui-patterns.com/patterns/GoodDefaults

Valeurs d'énumérations

Les valeurs d’énumérations suivent le même formalisme que les constantes. Elles sont en majuscules. Chaque mot est séparé par un  _  (exemple : MA_CONSTANTE).

Ce qu’il ne faut pas faire

monsieur
VALEURDEPI

Ce qu’il faut faire

MONSIEUR
VALEUR_DE_PI

Il est préférable de gérer en tant qu’énumération seulement les valeurs immuables (par exemple : civilité, sexe, jours, mois …) et limitées en nombre (moins de 5 à 6 valeurs). Les valeurs qui ont des chances de changer suite à des changements de standards, ou de besoins fonctionnels sont à bannir (par exemple : constructeur de voitures, type de monnaie, fuseaux horaires)

Ce qu’il ne faut pas faire

RENAULT, CITROEN, PEUGEOT, TOYOTA
EUR, USD, GBL

Ce qu’il faut faire

MR, MME, MLLE
HOMME, FEMME
LUNDI, MARDI, ..., DIMANCHE

3.3 Nommage des méthodes

Les méthodes sont des actions, elles doivent donc être nommées par des verbes. Utiliser une liste standard pour les nommages : L’idée est de se tenir sur les termes employés et réutiliser toujours les mêmes sur les différents : une meilleure cohérence assure une meilleure compréhension par tous les développeurs. screenshot

Les méthodes doivent avoir un nommage explicite qui doit idéalement d'auto-suffir sans documentation. Le nommage doit respecter le contrat et ne pas faire apparaître apparaître les détails d'implémentation.

Ce qu’il ne faut pas faire

rechercherTousLesLiensRecursivement
appliquerRegleRG004

Ce qu’il faut faire

RechercherLiens
calculerTauxInterets

4. DAO : Accès aux données

Les classes d'accès aux données ne doivent pas définir d'attributs. Suffixer les classes d'accès aux données par Dao ou Repository.

Ce qu’il ne faut pas faire

CatalogueDAO
CatalogueHibernate

Ce qu’il faut faire

CatalogueDao
ProductRepository

Les DAO travaillent sur les objets métiers. Les méthodes de DAO doivent cohérents entre les DAO. Utiliser une liste standard pour les nommages : L’idée est de se tenir sur les termes employés et réutiliser toujours les mêmes sur les différents DAO.

Dictionnaire de termes

  • Create, Créer
  • Retrieve, Find, Récupérer, Chercher
  • Update, Modifier, Maj (Mettre à jour)
  • Delete, Supprimer

Par exemple : retrieveStations()

Pour les find qui se font sur d’autres éléments que la clé, on utilise By ou Par (Par exemple : findModemByIp, chercherGaresParRegion)

Astuce
Garder le nommage des pluriels : retrieveTrain() retourne un seul train. retrieveTrains() (avec un ‘s’) retourne une collection de trains.

Ce qu’il ne faut pas faire

lireAllTrain
getTrain
mettreAJour
putTrain, insertTrain
removeTrain
delete_Train

Ce qu’il faut faire

recupererTrains,retrieveAllTrains, findAllTrains
recupererTrain
modifierTrain ou majTrain
createTrain
deleteTrain
deleteTrain

Bonne pratique : la pagination
Ne pas oublier une limite sur le nombre de résultats retournés par les méthodes de type retrieve. Il est préférable de prendre en compte la pagination des résultats, ou à minima, la limite du nombre de résultats retournés dès la conception.

5. Traitements Métier

Suit le même formalisme que les Dao mais en suffixant avec Service.

Ce qu’il ne faut pas faire

ProductManager ou GestionnaireVoiture
CatalogueSERVICE

Ce qu’il faut faire

ProductService
CatalogueService

5.1 Méthodes

Une méthode rend un service -> un verbe est plus représentatif pour nommer un service. Exemple : rechercherProduit, calculerInteretNets, enregistrerReservation. Eviter les termes faisant références aux accesseurs (is, get, set).

Ce qu’il ne faut pas faire

rechercheTrain
isAvailable
getNewCatalogue

Ce qu’il faut faire

rechercherTrain
validerDisponibilité
ajouterGare

Garder le découpage en termes de service métier.
Normalement les traitements métiers ne font pas office de passe-plat pour le DAO. On ne doit donc pas voir les termes spécifiques au DAO (pas de créer, ni modifier, etc.), mais plutôt les termes fonctionnels.

Dictionnaire de termes

  • Abonner
  • Activer
  • Ajouter (ex : Ajouter dans une liste de diffusion)
  • Affecter
  • Appliquer
  • Abandonner / Annuler
  • Calculer / Compute
  • Changer (ChangerEtat par exemple)
  • Cloturer / Fermer
  • Compléter
  • Compter
  • Confirmer / Valider
  • Contrôler
  • Désactiver / Inactiver
  • Déclarer
  • Détailler
  • Diffuser / Envoyer
  • Enregistrer / Register (le terme register en anglais est plus parlant)
  • Générer (Générer un PDF par exemple)
  • Marquer
  • Ouvrir (Ouvrir un compte par exemple)
  • Préparer
  • Process
  • Traiter / Réaliser (avec parcimonie car un peu trop fourre-tout)
  • Transférer
  • Replanifier
  • Réinitialiser / Remettre à zero / Reset / Vider
  • Rejeter
  • Rechercher
  • Verrouiller / Déverrouiller

Question : Comment gérer les cas qui sont proches du CRUD ?
Certains services sont clairement des opérations bas-niveau. Si j’ajoute un enregistrement sur l’interface, il s’agit d’un ajout qui ne nécessite pas obligatoirement de traitement métier spécifique. Dans ce cas, le service BLO est très proche du DAO.
Il faut essayer de lui apporter une valeur fonctionnelle.
Par exemple : Je souhaite ajouter un commentaire pour un utilisateur. La méthode du service sera probablement ajouterCommentaire(Utilisateur, Commentaire) alors que dans le DAO, on aura UtilisateurDao.updateUtilisateur(Utilisateur).
Pour récupérer des objets, on peut essayer d’ajouter l’apport fonctionnel du service par rapport au DAO.

6. Utilitaires

Suffixe par Helper ou Util. (Exemple : CodeBarreHelper)

Ce qu’il ne faut pas faire

CodeBarreUtilities

Ce qu’il faut faire

BarcodeHelper
BarcodeUtil

7. Présentation

Ci dessous, un exemple de nom d'activité qui peuvent être utilisés pour représenter les événements utilisateurs :

Dictionnaire de termes 

  • Sélection
  • Initialisation
  • Impression
  • Affichage
  • Modification
  • Rechercher
  • Valider
  • Annuler

8. Exceptions

suffixées par Exception.

9. En résumé !

  • AbstractXxx --> Classe Abstraites
  • XxxService --> Classe de Traitement métier
  • XxxConfig --> Classe de gestion de configuration
  • XxxConverter --> Classe ou Interface de conversion. Convertir des données (Xml -> CSV, etc.)
  • XxxException --> Classe d'exception
  • XxxFactory --> Classe de construction d'objets (Design Pattern Factory)
  • XxxUtil ou XxxHelper --> Classe utilitaire

Pour les applications Swing :

  • XxxFrame --> Les classes représentant des fenêtres
  • XxxLauncher --> Classe de lancement de l'application contenant le main()
  • XxxView --> Classe représentant une vue. (Design Pattern MVC)
  • XxxModel --> Classe représentant un objet de Model. (Design Pattern MVC)
  • XxxAction --> Classe d'écoute d'Action (héritant d'ActionListener) qui effectue un traitement sur un évenement utilisateur.
  • XxxController --> Classe de traitement de controlleur (Design Pattern MVC)