Améliorer le code - Episode 1

Améliorer le code - Episode 1

Introduction

Vous avez décidé d'améliorer la qualité de votre code et vous ne savez pas par où commencer, alors vous êtes au bon endroit.
Tout d'abord qu'est-ce qu'englobe la qualité ? Et bien le sujet est vaste, on peut parler de style de code, de performance, de tests, d'architecture, et encore certainement plein d'autres choses qui vous viennent en tête.

Dans cet article, on va, comme Orelsan dans son dernier album, reprendre les bases en abordant principalement un point : le style de code.

Pourquoi ce point est essentiel ?

  • parce qu'on s'est tous déjà retrouvé à perdre du temps pour résoudre un merge pour des problèmes d'indentation et de mise en page
  • parce qu'en partageant des normes communes, on facilite la relecture de son code pour les autres (ou même vous dans quelques mois)
  • parce qu'en organisant tous de la même façon, on debug plus rapidement
  • parce que plein de gens ont déjà débattus de ces questions et que plein de solutions existent

Ah oui aussi, je fais du PHP sous Symfony, donc si vous êtes dans votre cave en train de faire du COBOL, taxidermiste ou les deux en même temps, vous ne serez peut-être pas intéressé par ce qui va suivre.

 

Style du code (Code style)

Si vous pensez déjà tout savoir du style de code, passez directement à la suite en cliquant ici, sinon c'est parti pour la première partie (ça fait deux fois parti, ça sonne bizarrement non ?).

Shakespeare vs Molière

Vous passez votre temps à lire des docs en anglais, alors faites comme tout le monde, codez en anglais, en plus PHPStorm le comprend et pourra souvent remarquer des fautes de frappes. Et if you are not bilingue, vous pouvez utiliser le site WordReference pour vous aider à traduire correctement.

Formats d'écritures

Avant d'entamer la suite, un petit rappel sur les différents formats d'écriture qui sont utilisés couramment.

Le premier est le snake_case, on écrit tout en minuscules, et on attache les mots à l'aide d'un underscore.
Ex : l'attribute d'un product se nomme product_attribute

Le deuxième est UPPER_CASE, la version majuscule du snake_case
Ex : l'attribute d'un product se nomme PRODUCT_ATTRIBUTE

Vient ensuite le camelCase, on reprend le même principe que le snake_case, mais on passe la première lettre d'un mot à rattacher en majuscule
Ex : l'attribute d'un product se nomme productAttribute

Et pour terminer le PascalCase, qu'on trouve également appelé StudlyCase, ou en langage technique avancé le camelCase avec une majuscule au début
Ex : l'attribute d'un product se nomme ProductAttribute

Voilà, maintenant on peut vraiment commencer avec un récapitulatif des normes PSR1PSR2 et des conventions Symfony.

Alors les formats d'écriture, on utilise lequel pour quoi ?

Pour PHP en général :

  • Les noms de classes (et leurs fichiers) en PascalCase
  • Les fonctions, les arguments et les variables en camelCase
  • Les constantes en UPPER_CASE

Et pour Symfony :

  • Les dossiers et les fichiers PHP sont en PascalCase à l'exception des sous-dossiers du dossier Resources qui sont en snake_case. (Exemple(s) : AppBundle\Entity\Foo.phpAppBundle\Resources\views\)
  • Les fichiers .twig et .yml sont également écrits en snake_case
  • Le snake_case également, pour nommer une route ou déclarer un service

Aérations / Espacements / Retours à la ligne & cie

Attention, on attaque la partie la plus passionnante de cet article, c'est peut-être le moment de reprendre un café et SURTOUT de mettre votre portable en silencieux pour le respect des autres usagers.

Les lignes

  • Une ligne ne doit pas dépasser 120 caractères. Si une ligne est plus longue, c'est le signe qu'il faut rediviser son code en plusieurs (en créant des variables intermédiaires, faire des retours à la ligne...)
  • Une ligne doit comporter une  seule instruction (on évitera le if avec assignation de variable sur une seule ligne par exemple)

Les espaces

  • Avant chaque ouverture et après chaque ouverture de parenthèses, on met un espace, à l'exception des déclarations de fonction.
  • Pas d'espaces non plus lors d'une concaténation
  • Un espace également avant et après chaque opérateur d'assignations (=, +=, .=, ...) et les opérateurs arithmétiques (+, *, -, ...)
  • Un espace après la virgule de chaque argument de fonction (jamais avant)

Les lignes d'espacement

  • Ne jamais utiliser plus d'une ligne d'espacement. (S'il faut plus d'une ligne pour la lisibilité du code, il faut envisager de créer une fonction ou plusieurs fonctions de plus petite taille)
  • En créer le moins possible. Toujours chercher à "coller" le code vers le haut,  et créer une ligne lorsqu'il devient intéressant de distinguer un bloc de code d'un autre

Les accolades : {

  • Pour les déclarations de fonctions et de classes, mettre les accolades sur une nouvelle ligne
  • Dans les autres cas (ifelseswitchfor ...), les mettre en bout de ligne

Les déclarations : use

  • Les déclarer après le namespace sans ligne d'espacement
  • Les ranger par ordre alphabétique
  • Penser à supprimer les déclarations non utilisées

Propriétés

  • Déclarer systématiquement la visibilité (public, private ou protectecd) de chaque propriété
  • Une seule déclaration de propriété par ligne
  • Pas de underscore au début du nom pour les propriétés privées

Fonctions

  • Déclarer la visibilité de chaque fonction
  • Pas de underscore au début du nom pour les fonctions privées

Toujours là ? Félicitations, en moyenne seulement 18,37% arrive à tenir jusqu'ici selon un sondage Sopra Steria Ipsos.

Pour rendre toutes ces règles plus claires, voici un exemple de code ne respectant pas ces règles, puis l'exemple respectant les règles. Prenez le temps de les examiner pour mieux appréhender tout ce que vous venez de lire.

Exemple non standardisé / Exemple standardisé

Vous en êtes déjà là ? Ça me paraît un peu rapide.

Envie d'aller plus loin et de créer vos propres standards ? Vous pouvez consulter les liens pour voir les listes complètes des conventions PSR et Symfony.
Mais avant, une citation à garder en tête :

Faut pas essayer à tout prix d'être original, hein ! Tu vois ? Ta tête est déjà originale, faut pas surenchérir tu comprends ?
Victor Hugo - Dikkenek - Editions : C'est sur internet, ça doit être vrai

 

 

Automatiser l'application des règles

Bon c'est bien sympa toutes ces règles, mais vous vous dites certainement que vous n'allez jamais réussir à tout retenir tout de suite, je vous propose donc plusieurs solutions qui vous permettront d'appliquer de façon automatique ces règles.

PHPStorm

Si vous utiliser PHPStorm, vous avez certainement déjà utilisé le raccourci pour reformater votre code, sinon prenez l'habitude de le faire. Si vous ne connaissez pas encore le raccourci, aller voir dans Keymap > Reformat Code.

Et cette fonction est personnalisable pour chaque language (voir onglet Code Style), libre à vous de chercher vos propres réglages, mais par défaut vous pouvez utiliser les règles PSR1/PSR2 ou Symfony. Et surtout, partagez cette configuration si vous partagez à plusieurs.

Si vous souhaitez, vous pouvez utiliser la configuration que l'on utilise qui est disponible ici.

PHP-CS-Fixer

En plus de ce reformatage, je vous conseille d'utiliser un autre outil : PHP-CS-Fixer. C'est un outil qui est maintenu par Fabien Potencier (le gourou de Symfony), donc vous pouvez l'utiliser avec confiance.

Commencer par installer la commande sur votre machine, ensuite le plus pratique est de créer un fichier de configuration dans chaque projet.

Voici la configuration que l'on vous recommande : ici

Une fois ce fichier placé à la racine de votre projet, exécutez la commande suivante, et profitez du résultat :

 php-cs-fixer fix monDossierAReformater/

Je vous invite à aller lire plus en détail les règles utilisables pour trouver la configuration que vous souhaitez utiliser dans vos projets. Et si vous utilisez déjà l'intégration continue, vous pouvez facilement intégrer cet outil à votre process.

 

Mesurer la qualité

La confiance n'exclut pas le contrôle.
Lenine

Vous vous demandez certainement comment pouvoir contrôler que ces règles soient vraiment bien appliquées ? Voici donc un comparatif des outils disponibles pour vous aider à contrôler et également à mesurer objectivement la qualité de votre code.

scrutinizer

Ils revendiquent 30000 projets, sont compatibles avec PHP et permettent d'utiliser à la fois github, bitbucket et gitlab.

Les plus :

  • C'est un outil en ligne, rien à installer et à maintenir sur votre serveur
  • Il existe une configuration basique pour PHP, ainsi qu'un catalogue de règles à ajouter très complet. L'utilisation d'une configuration globale qu'on peut mettre à jour sans devoir reconfigurer chaque projet est également très pratique.
  • Vous avez la possibilité de lancer une analyse automatiquement à chaque push sur votre repository git.
  • Des métriques et des notes par classe et par fonction : complexité, duplication, dépendances ...
  • Des graphiques, c'est beau les graphiques

Les moins :

  • Première analyse longue
  • Payant pour les dépôts git privés
  • Pas de possibilité de créer vos propres règles

SensioLabsInsight

Un autre outil de SensioLabs qui s'intègre également avec github, bitbucket et gitlab.

Les plus :

  • C'est un outil en ligne, rien à installer et à maintenir sur votre serveur
  • Pas de configuration à faire
  • Détecte des mauvais comportements bien spécifiques à Symfony
  • On a des médailles

Les moins :

  • Règles assez légères
  • Payant même pour les projets publics
  • Personnalisation limitée des règles

SonarQube

Un autre outil, que je n'ai pas testé mais qui est certainement une bonne alternative aux précédents est SonarQube qui revendiquent 85000 projets.

Les plus :

  • Open-source, donc gratuit

Les moins :

  • Installation nécessaire avec un serveur d'intégration continue

Conclusion du comparatif

Pour répondre spécifiquement au problème de vérifications des règles de style, scrutinizer est certainement la solution la plus rapide et la plus pratique à mettre en place pour commencer.
SensioLabsInsight est un peu trop léger sur ce point, néanmoins ce n'est pas l'objectif principal de cet outil, on en reparlera certainement dans un autre article sur la sécurité ou la performance.
SonarQube est certainement un très bon remplaçant à scrutinizer, mais il nécessite d'être installé et configuré sur un serveur. On mettra à jour cet article dès qu'on aura eu l'occasion de le tester

 

Conclusion

Vous savez donc maintenant comment écrire du code proprement, appliquer rapidement ces règles et vérifier qu'elles sont appliquées. Néanmoins, votre code n'est pas forcément performant, testable ou sécurisé, on reparlera de ces points dans de futurs articles, n'hésitez pas à revenir ou nous suivre sur Facebook pour être tenus au courant.

Et avant de vous laisser je vous invite à méditer la réflexion suivante :
Si le rap appliquait également des standards de qualité, Jul aurait-il été autorisé à écrire ?

JF Thuillier