Un bon nommage dans un code permet une meilleur lisibilité du code facilitant son test, sa modification et son évolution sans recourir à une documentation exhaustive. Les équipes peuvent alors concentrer leurs efforts sur la production de fonctionnalités plutôt que de documentation: Working software over comprehensive documentation.

Intérêts du bon nommage

Si vous codez en Java il vous est certainement déjà arrivé de commencer à taper “au hasard” un nom de classe ou de méthode dont vous n’êtes pas certain de l’existence, l’assistance à la saisie de votre IDE aidant et une excellente convention de nommage qu’est celle de l’API java permet souvent de trouver la classe ou la méthode dont vous avez besoin sans ouvrir la documentation.

Outre l’utilisablité quand vous développez une librairie, un bon nommage rends le code facilement lisible et donc facile à valider et corriger.

Entre ce code:

int debit(int m) throws Exception {
    int a=solde-m;
    if(a < 0) update(-m);
    else throw new SoldeException();
    return a;
}

et celui ci:

int debiterCompte(int montantADebiter) {
    int soldeRestant=soldeCourrant - montantADebiter;
    if(soldeRestant < 0) mettreAJourSolde(-montantADebiter);
    else throw new ExceptionSoldeInsuffisant();
    return soldeRestant;
}

Il est plus facile de valider et déboguer le code dans le second exemple que dans le premier. Et l’erreur de comparaison du solde dans le deuxième cas se déclare par elle même à la relecture du code.

En effet, un bon nommage permet de lire le code comme si on lisait un texte est donc utiliser les capacités logiques de la vie courante pour valider le code.

Un vecteur d’agilité

Le deuxième principe de l’Agile Manifesto édicte

Working software over comprehensive documentation

Or la capacité de réduire la documentation sans faire courir de risque au projet dépend fortement de la lisibilité du code. Un bon nommage favorise cette lisibilité.

Cela est en lien avec une pratique du lean qu’st le Management Visuel

Le Management visuel est l’une des techniques lean conçue de telle sorte que toute personne entrant dans un atelier, même ceux qui
sont pas familiers avec le détail des processus, peuvent voir très rapidement ce qui se passe, comprendre et voir ce qui
est sous contrôle et ce qui ne l’est pas. (source)

Dans ce sens, un code lisible en soit favorise l’efficacité et améliore la quailité. En effet, un nouveau développeur arrivant sur un code lisible n’a pas besoin de documentation exhaustive pour le prendre en main et peut directement concentrer ses effort sur la valeur ajoutée à apporter au Product Owner.

Une documentation dit ce que fait le code, un code lisible dit ce qu’il fait mais aussi comment il le fait, cela encourrage alors le développeur, au besoin à améliorer améliorer le code quand l’opportunité se présente.

Syndrôme de la page blanche

Comme un écrivains on a face à l’écran un syndrome de la feuille blanche, syndrome qui pousse souvent à adopter des règles de nommage techniques ou sans aucun sens. Ainsi, j’ai eu dans mon équipe un développeur qui nommait les variables avec des combinaisons de ses initiales. Cela faisait en exagérant un peu quelque chose comme :

int jpl = 3;
int plj = 10;
if((plj-jpl)>23) doSomeThing(jpl);
....

Pour stimuler la créativité, dans la suite de l’artice je vais donner quelques tuyaux pour bien nommer les variables.

Quelques tuyaux pour trouver des idées pertinentes des noms de variables.

Chapter 1. Nommer une variable selon ce qu’on doit en faire

Comme par exemple {{{itemsToRemove}}} ici :

ArrayList itemsToRemove = new ArrayList();
for(MyType elem : myCollection) {
    if(elem.needsRemoval()) 
        itemsToRemove.add(elem);
}
myCollection.removeAll(itemsToRemove);

Cette approche est souvent plus pertinente pour les variables plutôt locales et éphémères qui ne sont utilisées que pour une tache précise dans l’algorithme.

Chapter 2. Nommer selon la nature de ce qu’elle contient

Comme unsold items dans :

ArrayList unsoldItems = getUnsoldItems();
for(Item item : unsoldItems) {
    item.setAsAvailableForSale();
}
...
warehouse.markAsAvailable(unsoldItems);
...
for(Item item : unsoldItems)
    paymentProvider.refund(item.getCustomerId(), item.getPrice());

Cette approche est souvent très pertinente et donne une lisibilité exceptionnelle au code.
Elle nécessite cependant de trouver une façon judicieuse pour décrire le contenu de la variable en peu de mots:

//Unsold items including new items returned by the user after delivery but not used ones.
ArrayList unsoldItems = ...

et non pas

ArrayList unsoldAndReturnedItemsButNotReturnedOnes = ...

En effet, une caractérisitique du bon nom est qu’il puisse être retenu par le lecteur, il se doit donc d’être succinct. Et de ce fait, 2 ou 3 mots sont un max.

Chapter 3. Nommage des booleans

La meilleure approche est de les nommer par en une affirmation logique qui est vraie quand la valeur du boolean est true. Ainsi, à comparer ces deux codes :

if(availibity && price) return false;

on comprends moins le sens que dans

if(itemIsAvailable && priceIsValid) return false;

cette approche permet de faire en sorte que les assertions logiques, même longues soient “vérifiables”

if(basketIsNotEmpty && (userHasPaymentInfo || basketIsAGift || !productIsPrivate)) allowDelivery();

Quelques pièges et solutions

1. Les noms trop longs : Quand il est absolument nécessaire de manipuler des notions dont le nom est trops long, une technique est d’utiliser un acronyme ou les initiales avec une définition dans un commentaire, mais c’est une technique à éviter et il est préférable de chercher des noms courts.

   //PSP : Payment Service Provider
   Operator selectedPSP = getSelection().geProvider();
   

2. Remettre le nom de la classe dans le nom de ses attributs. C’est une pratique à rejeter complètement, sauf dans d’extrêmement rares cas, cette approche ne fait que rallonger le texte sans apporter d’information du genre {{{ Product.price }}} n’a rien qui manque par rapport à {{{ Product.productPrice }}}. D’autant plus que dans le nommage des instances, la pratique de mettre le nom de la classe (ou de préférence une de ses spécialisation) est bonne :

   Product selectedProduct; //Bonne pratique
   

En conclusion

La rédaction d’un code lisible avec un bon nommage est un art. On peut souvent négliger le fait qu’il faut “coder pour être lu” non seulement par la machine, mais par soit même ou un autre qui dans plusieurs mois ou années aura affaire au code pour le corriger ou le faire évoluer. Quoi qu’on en dise, barder un code de commentaire ou l’accompagner de documentation est une technique beaucoup moins efficace et introduit de la rigidité et de la non-valeur dans le projet.