Des noms clairs



J'ai plusieurs fois insisté sur ce point dans les premiers TP du livre, et cette fois j'y reviens avec un peu plus d'explications.


Quand vous créez un script PHP, vous devez inventer des noms. Vous allez devoir donner des noms à différents types d'éléments :

  • les variables ;
  • les fonctions ;
  • les classes.


L'idée est simple : il faut que vous fassiez l'effort de choisir des noms de variables et de fonctions clairs et compréhensibles.


Par exemple, voici de mauvais noms de variables :

  • $temp ;
  • $data ;
  • $info ;
  • $val ;
  • $val2.


Je n'ai pas inventé ces noms de variables ; en fait, pour tout vous dire, ce sont des noms que j'ai vraiment vus dans de nombreux codes source.


Par exemple, $info : « info », oui, mais info sur QUOI ?


C'est pourtant ça qui est crucial : savoir ce que contient une variable. Une variable contient toujours une info, c'est à vous de préciser laquelle.


Je ne vous parle même pas des variables « sans nom » : $temp, $tmp et compagnie. Ces noms sont à bannir absolument.


Mais à quoi ça peut servir de chercher un nom de variable clair ? Après tout, c'est mon code, c'est pour moi, je comprends très bien ce que je fais !


Faux.
Bien sûr que vous savez ce que vous faites (personne n'est dans votre esprit, après tout). Et pourtant le problème peut apparaître dans deux cas.

  • Si vous donnez votre code PHP à un ami pour qu'il vous aide à un endroit où vous bloquez, ou pour qu'il continue votre code. Essayez par exemple de montrer votre code PHP sur des forums sur Internet, vous verrez que si vous utilisez des noms peu clairs, vous aurez beaucoup moins de réponses parce qu'il aura été bien plus difficile de comprendre le fonctionnement de votre code !
  • Un autre cas (sous-estimé), c'est celui où vous retouchez votre code plus tard. Je ne dis pas le lendemain (les idées sont encore fraîches), mais dans trois mois, ou même dans trois semaines. Croyez-en mon expérience : il m'est arrivé de devoir relire mon code source en me demandant « Mais qu'est-ce que j'ai bien pu vouloir faire, là ? ».


Passez ne serait-ce qu'une seconde de plus à réfléchir à des noms clairs. N'ayez pas peur de choisir des noms un peu longs, ce n'est pas une perte de temps, bien au contraire.
Vous pouvez utiliser le symbole underscore « _ » pour remplacer les espaces, qui sont, je vous le rappelle, interdits dans les noms de variables et de fonctions.


Voici quelques exemples de noms de variables clairs :

  • $ip_visiteur ;
  • $pseudo_membre ;
  • $date_news ;
  • $mot_de_passe ;
  • $forum_selectionne.


Pour finir, et en espérant vous convaincre (parce que croyez-moi, c'est très important), voici le même code source en deux exemplaires :

  • le premier contient des noms courts et pas clairs ; il est difficile de comprendre rapidement ce qu'il fait ;
  • le deuxième contient des noms un peu plus longs, mais au moins on arrive tout de suite à savoir à quoi sert telle variable ou telle fonction.

Ces deux codes produisent exactement le même résultat ; simplement, l'un d'eux est beaucoup plus compréhensible que l'autre.


Des noms de variables peu clairs

<?php

$mess_page = 20;

 

$ret = $bdd->query('SELECT COUNT(*) AS nb FROM livre');

 

$data = $ret->fetch();

$total = $data['nb'];

  

$nb_total  = ceil($total / $mess_page);

  

echo 'Page : ';

for ($i = 1 ; $i <= $nb_total ; $i++)

{

    echo '<a href="livre.php?page=' . $i . '">' . $i . '</a> ';

}

  

?>

Des noms de variables beaucoup plus clairs


<?php

$nombreDeMessagesParPage = 20;

  

$retour = $bdd->query('SELECT COUNT(*) AS nb_messages FROM livre');

$donnees = $retour->fetch();

$totalDesMessages = $donnees['nb_messages'];

  

$nombreDePages  = ceil($totalDesMessages / $nombreDeMessagesParPage);

  

echo 'Page : ';

for ($page_actuelle = 1 ; $page_actuelle <= $nombreDePages ; $page_actuelle++)

{

    echo '<a href="livre.php?page=' . $page_actuelle . '">' . $page_actuelle . '</a> ';

}

?>

C'est fou comme des noms écrits correctement en français permettent d'y voir plus clair.

Créé avec HelpNDoc Personal Edition: Écrire des livres électroniques ePub pour l'iPad