Livre “Coder Proprement” : 6 règles pour un nommage optimal

Le livre de développement Coder Proprement (ou Clean Code dans sa version originale) a été écrit par Robert C. Martin. Développeur professionnel depuis 1970, il devint également consultant logiciel international en 1990. Pour rédiger ce livre, l'auteur s’est entouré d’une équipe de développeurs aguerris afin de partager les meilleures pratiques en matière de code.

L’objectif du livre Clean Code est donc d’acquérir les notions de base du bon code et de comprendre les avantages qu’il procure. Il donne les clés permettant de transformer le mauvais code en bon code.

Cet article est un premier retour sur le livre de Robert C. Martin. Nous revenons principalement sur la première partie “Le Nommage”. L'auteur y donne une définition de ce qu'il considère être du bon code. Cette partie traite également de la difficulté de nommer des objets et variables dans le développement informatique.

Prendre le temps de bien coder, c'est important

Quand "Plus tard" signifie "jamais" 

Dans Coder Proprement, l'auteur revient sur l'un des freins principaux au bon code : le sentiment de manquer de temps. Cependant, un code bâclé est la source même d’une perte de temps inévitable à plus ou moins long terme. 

Souvent, lorsque nous manquons de temps, nous pensons que nous reviendrons plus tard pour nettoyer ou factoriser le mauvais code. Mais pensez-vous réellement trouver plus de temps plus tard ?

Dave LeBlanc exprime son opinion dans sa loi Leblanc : “Plus tard signifie jamais”(de l'anglais Later Equals Never). En effet, remettre à plus tard revient souvent à ne jamais terminer proprement son travail, trop occupé par les nouvelles missions. Il est donc important de s'organiser de manière optimale afin de dédier à son code le temps qu'il mérite, au moment voulu.

Laissez le code plus propre que vous ne l'avez trouvé

Une autre citation adapte une règle de boy scoot pour la transformer en règle de base du bon code : “Laissez le campement plus propre que vous ne l’avez trouvé en arrivant.” devient “Laissez le code plus propre que vous ne l’avez trouvé.”

En effet, si chacun rend le code un peu plus propre que celui qui a été récupéré, le code ne peut pas se dégrader. Un simple nettoyage peut parfois être très utile. Renommer une variable, découper une fonction ou supprimer une légère redondance peut, par exemple, améliorer la qualité du code.

Bien nommer les éléments de code

La première partie du livre concerne un problème récurrent bien connu des développeurs : le nommage de variables, classes, fonctions, etc. Cependant, chaque développeur a sa propre définition du bon code. Il est parfois compliqué de trouver une vérité absolue sur ce qu’est Le Bon Code.

L’auteur se base ici sur son expérience pour transmettre sa propre vision des bonnes pratiques, notamment en ce qui concerne le nommage.

Voici donc une liste de 6 règles proposées dans le livre pour un nommage optimal.

1. Révéler ses intentions dans le nom

Selon Robert C. Martin, la première règle de base en matière de nommage est  d’utiliser un nom révélateur des intentions. Ce nom doit informer sur sa raison d’être, sa mission et son usage.

int d; // Temps écoulé en jours.

Dans l’exemple ci-dessus, le nom ne donne aucun indice sur l'utilité de la variable. Le fait d’utiliser un commentaire aurait dû avertir le développeur que le nom n’est pas adapté. 

Autre exemple de traitement simple, mais incompréhensible :

public List<int[]> getThem() {

  List<int[]> list1 = new ArrayList<int[]>();

  for (int[] x : theList)

    if (x[0] == 4)

      list1.add(x);

  return list1;

}

Alors qu’avec une simple bonne utilisation du nommage, le même code devient parfaitement compréhensible :

public List<int[]> getFlaggedCells() {

  List<int[]> flaggedCells = new ArrayList<int[]>();

  for (int[] cell : gameBoard)

    if (cell[STATUS_VALUE] == FLAGGED)

      flaggedCells.add(cell);

  return flaggedCells;

}

2. Eviter les noms qui donnent de mauvaises informations

Règle numéro 2 : éviter les noms qui désinforment sur l’usage :

• éviter les faux indices donnés par le nommage, comme une abréviation qui peut avoir plusieurs sens (hp pour hypoténuse, par exemple)
• éviter de répéter le type de la variable dans le nom (AccountList alors que la variable n’est pas une List)
• éviter d’utiliser des noms trop proches (XYZControllerForEfficientHandlingOfStrings et XYZControllerForEfficientStorageOfStrings)

3. Utiliser des noms distinctifs

Utiliser des noms quasi-similaires rend également le code plus difficile à comprendre. Si un nom est déjà utilisé, il faut éviter de créer une variante avec une faute d’orthographe ou un chiffre (a1, a2). Par exemple :

public static function copyChars(array a1, array a2) 
{
  for (int i = 0; i < count(a1); i++) {
    a2[i] = a1[i];
  }
}

Dans ce cas, si "a1" était nommé "source" et "a2" était nommé "destination", la lisibilité serait nettement meilleure.

Il est également préférable d'éviter les mots parasites dépourvus de sens comme Data, Info (ProductInfo et ProductData, qu’est-ce qui les différencie ?), variable ou type de donnée (nameString alors que name est explicite sur ce qui est attendu comme type de donnée).

On peut également noter ces autres conseils de nommage :

• Choisir des noms prononçables : plus simple pour en parler entre développeurs
• Choisir des noms compatibles avec une recherche : un nom de constante (MAX_CONTACTS_PER_LIST) est plus simple à rechercher que sa valeur (50)
• Éviter la codification : par exemple éviter de :
  • préciser le type dans le nom, phoneString alors que la variable est maintenant de type number
  • répéter la lettre I dans IShapeFactory pour préciser que c’est une interface
• Choisir un mot par concept : on s’attend à avoir le même principe pour les classes avec le même suffixe
• Ne pas hésiter à utiliser des termes techniques (s’ils font partie de la culture des développeurs) et à utiliser des termes du métier (s’il n’existe aucun terme informatique sur ce qui est en train d’être fait).

4. Nommer les classes avec des noms

Concernant les classes, l’auteur invite les développeurs à choisir des noms ou groupes nominaux comme Customer, ZipcodeParser. Il conseille d’éviter les termes comme Manager, Processor, Data ou Info. Le nom d’une classe ne doit pas être un verbe.

5. Nommer les méthodes avec des verbes 

La bonne pratique pour nommer les méthodes est de choisir des verbes ou groupes verbaux. Par exemple : postArticle, deleteArticle, save, getContact.

• Les accesseurs, mutateurs et prédicats doivent être nommés selon le standard du langage (souvent getX, setX ou isX)
• En cas de surcharge de constructeur, il faudrait utiliser des méthodes de fabrique statiques avec un nom explicite sur ce qui doit être donné en paramètre

Complex fulcrumPoint = Complex.FromRealNumber(23.0);

au lieu de :

Complex fulcrumPoint = new Complex(23.0);

On peut forcer l’utilisation de l’appel de la méthode de fabrique en rendant privé le constructeur.

6. Décrire les effets secondaires

Les noms doivent décrire tout ce que fait une fonction, quitte à mettre plusieurs verbes dans le nom de la fonction :

public function getInstance(): Instance

{

    if ($this->instance == null) {

        $this->instance = new Instance();

    }



    return $this->instance;

}

Par exemple, cette fonction devrait plutôt s’appeler "CreateOrReturnInstance" car elle ne retourne pas uniquement une Instance, mais elle la crée également.

Conclusion : bien nommer, la base du bon code

Renommer fait souvent peur car cela peut impliquer de nombreux changements. Cette tâche est néanmoins largement simplifiée grâce aux outils de refactoring des IDE récents.

Finalement, le nommage n’est pas une compétence technique mais plutôt une aptitude à bien décrire et partager ce qui est fait. Respectez cet ensemble de règles de nommage améliorera la lisibilité du code et aidera lors de maintenance ou d’évolution.