Normes de codage : quelque chose à flairer

Certaines questions existent depuis aussi longtemps que le développement de logiciels. Dois-je mettre en retrait avec des tabulations ou des espaces ? Les normes de codage sont-elles vraiment si importantes ? Dois-je vraiment perdre du temps à suivre des règles arbitraires ?

Respectivement, les réponses à ces questions sont : onglets (évidemment), oui (moins évidemment) et non (en quelque sorte).

L'importance des normes a été longuement abordée par d'autres, je n'entrerai donc pas dans les détails ici, mais l'essentiel est le suivant : la cohérence interne est souhaitable au sein d'un projet donné car elle améliore la lisibilité, limite les surprises et peut contribuer à la robustesse du code.

Vous n'avez pas besoin de « perdre du temps » à vous en tenir aux normes car il existe des moyens d'appliquer ces normes automatiquement !

Ce que je vais couvrir ici est un moyen de configurer rapidement et facilement l'outil autonome PHP Codesniffer (PHPCS) pour les projets WordPress. Cela vous permettra de :

• Produire un rapport sur la conformité aux normes dans votre code
• Résoudre automatiquement une grande variété de problèmes de conformité

Nous allons implémenter les normes WordPress dans les exemples qui suivent.

Installation

Conditions préalables:

• Accès au terminal (les utilisateurs de Windows peuvent avoir du succès avec Bash pour Windows mais cela n'a pas été testé)
• Gestionnaire de package compositeur

Bien qu'il soit possible d'installer PHPCS par lui-même, il ne prend pas en charge WordPress par défaut. Pour cela, nous allons installer les standards de codage WordPress (WPCS).

Tout d'abord, accédez à l'endroit où vous souhaitez installer WPCS pour une utilisation mondiale.

 $ > cd /chemin/vers/où que ce soit

Installez le package avec composer.

 $ > composer create-project wp-coding-standards/wpcs --no-dev

À ce stade, nous pourrions plonger et commencer à utiliser WPCS, mais il y a quelques indicateurs à définir chaque fois que nous exécutons la commande. Mettons en place quelques alias pour plus de commodité.

Ouvrez .profile depuis votre répertoire personnel dans votre éditeur préféré (ou créez-le s'il n'existe pas) et ajoutez ce qui suit :

 # Normes de codage WP
export PATH=$PATH:"/path/to/wherever/wpcs/vendor/bin"
alias wpcs='phpcs --standard=WordPress --extensions=php
alias wpcbf='phpcbf --standard=WordPress --extensions=php

Nous avons ajouté ici deux alias – un pour phpc (qui trouve et affiche les échecs de conformité) et un pour phpcbf (qui résout automatiquement divers problèmes détectés par phpcs). Les options supplémentaires effectuent les opérations suivantes :

–standard=WordPress – applique les normes WordPress (définies dans WPCS)

–extensions=php – cibler les fichiers PHP uniquement (PHPCS cible PHP, CSS et JS par défaut)

Redémarrez le Terminal (ou source .profile ) et WPCS est prêt à renifler votre code !

Reniflement

Pour produire un rapport d'analyse sur un fichier, exécutez la commande suivante :

 $ > wpcs /chemin/vers/votre/php/projet/fichier.php

Cela produira le rapport dans le terminal. Alternativement, vous pouvez exporter ceci dans un fichier :

 $ > wpcs /chemin/vers/votre/php/projet/fichier.php > sortie.txt

Le rapport Sniff

Votre sortie de reniflage WPCS ressemblera à ceci :

Il y a une bonne quantité d'informations emballées ici, mais elles sont assez clairement présentées. Passons en revue ce que nous avons :

• Le fichier ciblé
• Un résumé du nombre d'erreurs/d'avertissements trouvés et du nombre de lignes concernées
• Une liste des problèmes détectés, avec des niveaux de gravité et des descriptions
• Une indication du nombre de problèmes que phpcbf peut résoudre automatiquement (essentiellement tous les problèmes avec un [x])

Comme on pouvait s'y attendre, PHPCS ne peut pas tout expliquer. Il ne fera pas d'hypothèses sur le choix de la ponctuation dans les commentaires et certains types de formatage de code, mais il peut gérer une grande variété de problèmes pour vous.

Un bon bonus est que les règles WordPress permettent à PHPCS de détecter les problèmes spécifiques à WordPress, y compris l'utilisation abusive potentielle des fonctions.

Fixation

La résolution automatique des problèmes ne pourrait pas être plus simple :

 $ > wpcbf /chemin/vers/votre/php/projet/fichier.php

Un bref résumé est affiché :

Toutes les erreurs restantes devront être corrigées manuellement, mais vous constaterez généralement qu'une bonne partie des problèmes ont été résolus.

Règles personnalisées

Vous pouvez également souhaiter personnaliser l'ensemble de règles, exclure certains répertoires de votre projet, etc. La documentation du jeu de règles annoté PHPCS fournit des exemples de toutes les modifications que vous pouvez apporter, mais en gros, vous n'avez qu'à :

1. Créer un fichier de jeu de règles
2. Référencez-le dans la commande PHPCS

Voici un exemple de fichier de jeu de règles :

 <?xml version="1.0"?>
<nom du jeu de règles="Normes de codage WordPress">
    <description>Normes WordPress personnalisées.</description>
    <règle ref="WordPress">
        <exclude name="Generic.Formatting.MultipleStatementAlignment.NotSameWarning"/>
    </règle>
    <exclude-pattern>*/bin/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/tests/*</exclude-pattern>
</règles>

Dans l'exemple, nous avons effectué les opérations suivantes :

• Référencement du jeu de règles WordPress (de WPCS)
• Exclusion d'une règle
• Exclu certains répertoires

Le fichier de jeu de règles peut être placé dans n'importe quel répertoire à partir duquel vous appelez WPCS (le projet, le thème ou la racine du plugin est généralement judicieux) et référencé via un indicateur. Mettez à jour l'indicateur –standard dans votre .profile, comme ceci :

 # Normes de codage WP
export PATH=$PATH:"/path/to/wherever/wpcs/vendor/bin"
alias wpcs='phpcs --standard=codesniffer.ruleset.xml --extensions=php
alias wpcbf='phpcbf --standard=codesniffer.ruleset.xml --extensions=php

Pour vérifier quelles règles sont signalées lorsque vous exécutez WPCS, exécutez-le simplement avec l'indicateur -s comme ceci :

 $ > wpcs -s /chemin/vers/votre/php/projet/fichier.php

Et ensuite ?

Le guide ci-dessus vous permettra d'effectuer des contrôles de conformité aux normes ad hoc dans votre projet WordPress, mais si vous souhaitez l'intégrer dans votre cycle de développement standard, la prochaine étape logique est l'automatisation.

Envisagez d'intégrer PHPCS dans un exécuteur de tâches tel que gulp ou grunt (les modules PHPCS sont disponibles pour les deux), ou de l'intégrer dans votre pipeline de construction CI/CD.

Pour obtenir de l'aide sur le développement et la conception Web, contactez-nous dès aujourd'hui.

Si vous avez besoin d'aide avec votre n'hésitez pas à nous contacter.