Accueil 🔧 Tutoriel Astuces de Dev Web n°7 : Le reformatage ou refactoring de code
Astuces de Dev Web n°7 - Le reformatage ou refactoring de code

Astuces de Dev Web n°7 : Le reformatage ou refactoring de code

par Jérémy PASTOURET
Publié : Mis à jour le

Le reformatage du code est un vaste sujet dans le domaine du développement. Certains développeurs ont leur petites manies ; d’autres sont plus désorganisés, en mode fouillis. Tout dépend de la personnalité de chacun. Et puis quand on travaille en équipe, une charte commune émane naturellement. Même s’il y en a toujours qui ne sont pas d’accord, et se laissent aller au bout de quelques semaines.

Donc, dans cet article, je vais vous parler des petits manies de mon équipe et des bonnes pratiques en PHP. Vous allez aussi découvrir que PHPStorm est particulièrement intelligent, et qu’il permet d’effectuer des modifications de styles très rapidement. L’avantage, c’est de pouvoir récupérer un projet sur Github avec un style lourd et difficile à lire. Mais je vous parlerai de cette partie PHPStorm dans un prochain article.

Exemple de code à reformater, ou refactoring

Bannière développeurs

Je vais vous afficher le code dans un bloc (plus facilement copiable). Si vous avez envie de jouer le jeu et de faire l’exercice avec moi, vous pouvez récupérer mon code sur votre IDE favori, le tester et essayer de l’améliorer. C’est à dire le refactorer.

Mon projet se nomme LesEnovaZonePoor : il permet de créer des produits et de les ajouter dans un panier. Cette application PHP contient uniquement 2 fichiers :

  • Mon pseudo Controller qui se nomme Manager.php et qui appelle mes fonctions présentes dans ma classe Panier
  • Ma classe Panier

Le fichier Manager.php

Première version de Manager.php

Le fichier Panier.php

Première version du fichier Panier.php

Commençons par les choses de base qui nous gênent.

Short array or long array ?

Bannière problème

Depuis que PHP a sorti les « short array », j’en suis devenu un maniaque et je les transforme le plus possible (apparement on y gagne aussi en performance). Si vous ne savez pas ce qu’est un short array, ne vous inquiétez pas, voici un exemple :

On va prendre le constructeur de notre classe Panier, qui initialise un tableau de produit.
Voici le code avant

Avant modification 1 Panier.php

Et voici le code après

Après modification 1 Panier.php

Donc l’idée, c’est de transformer tout les array() en []. Et ça marche aussi avec des éléments à l’intérieur.
On peut prendre comme exemple la fonction d’ajout des produits.

Avant modification de Produit 2

Celle-ci devient

Après modification 2 Panier.php

J’ai supprimé le terme « array » et remplacé les parenthèses par des crochets.

Maintenant je vous propose de travailler sur la lisibilité de cette fonction. En effet, je trouve que ce n’est pas terrible à lire.

Un choix difficile : lowerCamelCase ou snake_case ?

Bannière question

Pour ma part, je préfère le lowerCamelCase que le snake_case. Pour ceux qui ne connaissent pas ces formats, le lowerCamelCase permet de mettre en minuscule le premier mot et d’appliquer une première lettre majuscule sur tout les mots qui se rajoutent à la variable. Tandis que le snake_case sépare les mot avec des underscores. On fait ça naturellement avec les noms de dossiers ou les noms de fichiers sur notre système d’exploitation favori. Pour la petite histoire du CamelCase, voici un lien Wikipedia.

Peut-on avoir plus d’informations dans le nom de la variable ?

bannière modernes

Pour que vous et vos collègues puissiez obtenir plus d’informations à la lecture /modification de votre code, je vous conseille fortement de rajouter une première lettre devant toutes vos variables pour en indiquer le type.

Notre fonction d’ajout de produits s’y prête bien.

Après modification 2 Panier.php

Vous remarquerez que c’est plus pratique à lire. Nous savons dès à présent que le code d’un produit est un « string » (une chaîne de caractères), que le prix est un numérique et que la propriété « produit » est un tableau de produits. Vous pouvez aussi utilisez la lettre « o » pour indiquer un objet, « f » pour un « float » et « b » pour un booléen. Vous avez dû remarquer que j’utilise uniquement du lowerCamelCase, c’est à dire que je commence par une minuscule puis je mets une majuscule sur le prochain mot : par exemple la variable « Date Of Birth » devient $sDateOfBirth. En effet, je n’aime pas trop le snake_case qui donne ce look-là : $_s_date_of_birth. Après, je pense que c’est une habitude à prendre, donc ce choix vous est réservé.

En ayant recours à cette pratique vous devrez adopter le lowerCamelCase, sinon vous vous retrouverez avec des variables de ce style :

$n_price, $s_name,

Comment obtenir de beaux tableaux PHP ?

Bannière petit pas

Je vous propose ensuite d’afficher joliment le tableau passé en paramètre array_push, comme ceci :

Après modification Panier 2

C’est la première étape, mais je pense qu’on peux faire encore mieux en ajoutant une tabulation au niveau des éléments du tableau.

Ce qui donne

Après modification 3 Panier

Concentrez-vous sur les noms de la fonction, des paramètres et des indices du tableau employés dans ce code. Y a-t-il quelque chose qui vous choque ?
Réponse : il y a un problème de cohérence. Un index du tableau est en français : « prix ». Sauf que le reste est en anglais. Le tableau quant à lui s’appelle Produit. Et pour le nom de la fonction, c’est pire, car on a un mélange anglais-français avec « addProduit ». Il faut donc faire un choix en équipe : soit écrire tout en anglais, soit tout en français. Et ça se discute aussi pour les commentaires.

Dans notre cas, il y a beaucoup plus d’anglais que de français. Par conséquent on migre tout en anglais, ce qui produit le code suivant

Après modification 4 Panier

C’est beau d’avoir des signes « égal » alignés ensemble

bannière Stop à l'obsolescence programmée

Est-ce nouveau ou perturbant pour vous ?
Vous risquez de dire que je suis maniaque, et je vous comprends. Car au début, je n’étais pas comme ça ! C’est un collègue de boulot qui m’a transmis le virus. Et maintenant, quand les signes « égal » ne sont pas alignés par rapport aux variables proches, ça ne me plaît pas.

Par exemple, imaginons qu’on récupère les données d’un formulaire passé en méthode « POST ». Côté PHP, on devrait avoir quelque chose qui ressemble à cela.

Exemple variables non-alignées

Vous préférez donc la version  ci-dessus ou la version ci-dessous, en termes de visibilité ? (sans parler de la praticité pour le développeur à aligner les « égal »).

Variables avec égales alignées

Après c’est un choix de style de code. Si la question du temps passé vous inquiète, je vous arrête tout de suite car dans le prochain article, je vous montrerai comment le faire en 2 secondes avec PHPStorm.

Le typage des paramètres et des retours de fonctions en PHP 7

Bannière Les actions

Une autre façon d’améliorer la lecture du code consiste à rajouter le typage des paramètres des fonctions introduites grâce à PHP 7. Ne vous inquiétez pas, on va y aller doucement. Je vous propose de partir sur une nouvelle fonction d’exemple : j’ai nommé le getProduct. Pour rappel, elle est développée de cette manière.

Avant modification getProduct 1

En rajoutant le type de paramètre, on obtient le résultat suivant

Après modification getProduct 1

Si votre IDE ne le reconnait pas, c’est que vous avez défini dans les paramètres de votre projet que la version de PHP utilisée est < 7.0. Si vous ne trouvez pas, je vous le montrerai dans un prochain article sur PHPStorm et le reformatage de code.

Concernant le typage du paramètre, vous pouvez aussi mettre « array », « object », « Product » (oui le nom d’une classe ça marche aussi). Cette façon d’écrire du code a deux avantages : la première, c’est que lorsque vous appelez cette fonction, votre IDE peut vous spécifier ce que la fonction attend comme paramètres. Si vous n’avez pas les bons types, votre IDE souligne la ligne en rouge et vous avertit du problème. Si vous connaissez un collègue qui risque de mal utiliser votre fonction, il se fera engueuler par PHP lorsque qu’il affichera la page. Car PHP vous informera sur votre page que le type passé ne correspond pas au type attendu. Donc pour conclure, toujours plus de visibilité et de vérification.

On peut aller encore plus loin en ajoutant le type retourné par la fonction. Voici le résultat sur notre précédente fonction

Après modification getProduct 2

Ce qui peut paraître bizarre au début… mais on s’y fait.
Petite explication et détails pour typer les retours de fonction :
– il faut ajouter « : » après la parenthèse de fin de votre fonction.
– le « ? » signifie que la fonction peut retourner null ou le type indiqué, dans notre cas Produit.
– tout comme le typage des paramètres, vous avez les mêmes possibilités.

C’est plus jolie sans accolade ?

Bannière métro - Pourquoi passer au Dark mode ou mode sombre

Je n’en ai pas fini avec cette fonction getProduct qui me pose encore problème. Vous devez savoir qu’en PHP les accolades ne sont pas obligatoires dans certain cas. Par exemple dans getProduct, le for et le if n’en ont pas besoin car ils exécutent une seule instruction chacun. A partir du moment où il y en a plusieurs, il faut mettre des accolades. Alors quand on code nous-mêmes ce genre de choses, on trouve ça super clair et on en est fiers. Mais quand on le lit dans un code qu’on n’a pas écrit, c’est autre chose. C’est la raison pour laquelle je vous conseille fortement de mettre des accolades PARTOUT.

Toujours pas convaincu ? Je peux vous dire que de nombreux bug ont été générés à cause de ça. Un développeur qui ne voit pas qu’une instruction principale est dans un if – ou pas – peut modifier des valeurs issues d’un calcul ou autre… et causer des dommages importants. De nombreuses histoires existent sur le sujet : on a perdu beaucoup d’argent, voire même des vies humaines avec ce genre d’erreurs. Allez jeter un œil sur cette page wikipedia : Mariner_1.

Pour en revenir au code, voici le rendu en rajoutant les accolades

Accolade ajoutée à la fonction getProduct

Pour en finir sur ce sujet, il est important de faire un choix commun avec l’équipe concernant le positionnement des accolades sur les fonctions.

Option 1 : Avec retour à la ligne

Accolade ajoutée à la fonction getProduct avec retour à la ligne

Option 2 : Sans retour à la ligne

Accolade ajoutée à la fonction getProduct sans retour à la ligne

Vous allez me dire que ce n’est pas grand chose, mais je peux vous dire que Git vous remerciera, et que ça vous évitera de nombreux conflits de code.

Les commentaires ça sert à quelque chose ?

Bannière choix

Oui, les commentaires servent à quelque chose. Sur ce sujet, il y a plusieurs tendances dans le mode du dev. Selon les hard codeurs (je crois qu’on les appelle comme ça), pas de commentaire du tout, c’est mieux. Cela veut dire qu’ils codent tellement bien et clairement qu’il n’y a pas besoin de commentaire pour comprendre le code. Alors peut-être que je ne code pas aussi bien qu’eux. Mais je sais qu’en fonction des cas, on est obligé de mettre des commentaires… surtout si on doit développer un algo costaud.

Donc tout est une question de dosage. Vous devez en mettre là où ce n’est pas clair, voire vous poser des questions et améliorer le code par la suite. Il faut aussi se mettre d’accord avec l’équipe sur la rédaction en anglais ou en français des commentaires. Cela varie en fonction des projets : il y aura-t-il des devs étrangers ? Si oui, il faudrait partir sur l’anglais. Sinon optez plutôt pour le français car les commentaires seront plus riches (on a plus l’habitude de décrire en français qu’en anglais).

Petite astuce, vous pouvez utiliser certains mots-clés intéressants en PHP. Je vous présente le « TODO » qui permet d’indiquer au dev (ou à soi-même) quelque chose à modifier dans le code, mais qui est secondaire. Par exemple dans la fonction d’ajout de produit, j’ai inséré un commentaire TODO.

Ajout de commentaire avec des mot-clés

Je vous présente aussi le « FIXME » qui est un niveau supérieur, reconnu lui aussi par votre IDE favori. Il permet d’alerter le dev sur un problème plus ou moins urgent à réparer. Par exemple avec la fonction de suppression d’un produit dans le panier.

Utilisation du mot-clé FIXME dans les commentaires

Et pour ceux qui aiment les documentations, vous pouvez aussi documenter les fonctions – si vous avez le temps, bien sûr. Il faut commencer par une petite description de la fonction, suivie des paramètres de la fonction et terminée par le retour de la fonction. Voici un petit exemple avec la fonction de récupération d’un produit.

Utilisation de doctype dans les commentaires

On peut mettre plusieurs commentaires @param pour les paramètres mais il n’y aura toujours qu’un seul @return car on ne peut retourner qu’un seul objet. Par exemple :

Utilisation de @param dans les commentaires

Conclusion

Bannière conclusion

Pour devenir un professionnel du reformatage de code, je vous invite à récupérer le code à reformater et de vous entrainer. Ensuite je vous conseille de comparer votre version avec ma correction.

Afin de récupérer le code de base et la correction, vous devez remplir le formulaire ci-dessous.

J’espère que ça vous a plu ! L’article suivant vous permet de faire la plupart des choses présentées ici en moins de 2 secondes, grâce à PHPStorm.

Vous pourriez aussi aimer

2 commentaires

Philippe 6 mai 2018 - 13 h 16 min

Bonjour,
Très intéressant cette suite d’articles « Astuces de dev » 🙂
Mais j’attends la suite, notamment « dans le prochain article, je vous montrerai comment le faire en 2 secondes avec PHPStorm. »
Et si possible avec moins de gif animés pour ponctuer chaque paragraphe : je n’en vois pas l’intérêt, ça fatigue l’œil qui est sans arrêt attiré par le « mouvement » et donc ça distrait la lecture, la concentration (j’en ai besoin de cette concentration, car certains articles sont parfois un peu difficile à appréhender au premier abord).
Quoi qu’il en soit, merci pour toutes ces astuces.
Philippe

Répondre
Jérémy PASTOURET 18 mai 2018 - 12 h 09 min

Bonjour, j’apprécie de recevoir des commentaires constructifs comme le votre. J’ai temporairement mis de côté cette série d’articles pour développer d’autres thématiques. L’article que vous attendez sortira très prochainement.
Jérémy.
PS : les avis comme le vôtre me permettent d’orienter mes sujets au plus près des besoins de mes lecteurs. S’il y a des thèmes particuliers qui vous intéressent, n’hésitez pas à m’en faire part.

Répondre

Laisser un commentaire

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.