Une des opérations de refactoring les plus élémentaires est le renommage des variables pour les rendre plus explicite. Les noms abondent dans les applications Web. Nous nommons les variables, les fonctions, les arguments, les classes et les paquetages. Nous nommons les fichiers sources, les ressources et les répertoires qui les contiennent. Il est préférable de bien les choisir. Cette article va essayer de vous montrer à travers des exemples l'apport qu'un nom de variable explicite peut avoir sur votre application.

Chosir des noms explicite

Il faut savoir que choisir un bon nom prend du temps, mais permet d'en gagner plus encore. Il ne faut pas hésiter à changer de nom lorsque vous en trouvez un meilleur. La personne qui relira votre code vous en sera reconnaissant

Le nom d'une variable, d'une fonction, d'une classe doit répondre à 3 questions essentielles :

• la raison de son existence
• son rôle
• son utilisation

Exemple de variables mal nommée

private $d;  // Temps écoulé en jours

Si un nom exige un commentaire, c'est que le nom n'est pas bon, c'est un moyen simple de savoir si le nom que vous avez donné est bon ou pas.
Le nom $d ne révèle rien. Il n'évoque pas une durée écoulée, pas même des jours. Suivant le contexte, la variable $d aurait du s'écrire :

private $elapsedTimeInDays;
private $daySinceCreation;
private $daySinceModification;
private $fileAgeInDays;

La lecture du nom de la variable apprend énormément de chose sur la donnée qu'elle va contenir. La personne qui reprendra le projet sera beaucoup plus efficace pour faire les modifications demandées.

L'importance d'un code explicite

Un petit exemple qui va vous rappeler sans doute de nombreux code source que vous avez déjà rencontrés au cours de votre carrière. Il casse pas des briques mais va nous permettre de véritablement mettre en avant les avantages qu'apporte un nommage explicite des variables et des noms de méthode.

public function getThem() {
  $list1 = array();
  foreach ($this->list as $x) {
    if (x[0] == 4) {
      $list1[] = x;  
    }
  }
  return $list1;
}

Le code n'est pas complexe à comprendre loin de la, mais il n'est pas du tout explicite. Le code implique que nous connaissons les réponses aux questions suivantes :

• Que contient dans la variable $list ?
• A quoi correspond la valeur contenu à l'indice 0 d'un élément de $list ?
• Quelles est la signification de la valeur 4 ?
• Comment j''utilise la variable retournée ?

Ces réponses ne sont pas données dans l'exemple, et c'est bien la le problème, elle devrait l'être.

Supposons que nous travaillons sur un jeu de demineur (je suis un grand fan). Nous pouvons améliorer notre code en rendé explicite plusieurs éléments :

• la variable $list contient l'ensemble du plateau de jeu, un nom comme $gameBoard sera donc beaucoup plus adapté
• Chaque cellule est représenté par un tableau, la première cellule correspond à l'état de la case, la valeur 4 correspond à l'état "Marquée"

Notre code se réecrit avantageusement sous la forme suivante.

public function getFlaggedCells() {
  $flaggedCells = array();
  foreach ($this->gameBoard as $cell) {
    if ($cell[STATUS_VALUE] === FLAGGED) {
      $flaggedCells[] = $cell;
    }
  }
  return $flaggedCells;
}

La simplicité du code n'a pas changé. Il contient toujours exactement le même nombre de ligne de code, d'opérateurs ou de constantes. En revanche, le code est beaucoup plus explicite.

Nous pouvons encore aller plus loin dans le refactoring, et écrire une simple classe pour les cellules au lieu d'utiliser un tableau. Ainsi, on peut cacher les constantes magiques que l'on a introduit précédemment.

public function getFlaggedCells() {
  $flaggedCells = array();
  foreach ($this->gameBoard as $cell) {
    if ($cell->isFlagged()) {
      $flaggedCells[] = $cell;
    }
  }
  return $flaggedCells;
}

Grâce à quelques changement simple sur le nommage des variables, on aura réussi à améliorer l'information véhiculé par notre code. Notre code est beaucoup plus explicite. C'est la toute la puissance d'un choix de nom approprié.