Quelle est l'utilité de PHP CodeSniffer? Application des normes de code en général?
J'essaie de mettre en place PHP CodeSniffer sur notre serveur d'intégration continue dans le but d'améliorer la qualité de notre base de code. Après avoir lu la documentation, je suis très enthousiaste à l'idée de normaliser et d'appliquer nos normes de codage. Cependant, je me pose des questions sur l'amélioration réelle de notre produit. Je sais bien que le renifleur ne détecte que les violations d'une norme de codage définie, mais quel type d'avantages une base de code propre et cohérente offre-t-elle? Vaut-il la peine de refaire un projet avec plus de 100k lignes de code pour se conformer à la norme PEAR?
Pour ceux qui ne connaissent pas PHP CodeSniffer ou l'odeur de code en général, voici un exemple de sortie:
FICHIER: /path/to/code/myfile.php
TROUVE 5 ERREUR (S) AFFECTANT 2 LIGNE (S)
-
2 | ERREUR | Commentaire de document de fichier manquant
20 | ERREUR | PHP les mots clés doivent être en minuscules; attendus "faux" mais trouvés "FAUX"
47 | ERREUR | Ligne non indentée correctement; prévu 4 espaces mais trouvé 1
51 | ERREUR | Commentaire de document de fonction manquant
88 | ERREUR | Ligne non indentée correctement; prévu 9 espaces mais trouvé 6
À strictement parler, l'utilisateur/client ne remarquerait aucune différence dans un produit qui a été refactorisé pour être conforme aux normes, mais je me demande s'il y a d'autres avantages cachés
À l'heure actuelle, notre code n'est en aucun cas bâclé et nous essayons de suivre nos propres normes personnelles qui, pour la plupart, sont dérivées de Pear's Coding Standards mais un œil averti peut repérer les différences.
Ma question est donc de savoir dans quelle mesure ils améliorent la qualité d'un produit. Quels avantages latents en ont résulté?
Suis-je simplement obsessionnel-compulsif avec mon désir de rapprocher notre produit d'un ensemble de normes? Est-ce que ça en vaut la peine? Si oui, quel type de stratégie avez-vous utilisé pour implémenter le renifleur de code et corriger les violations suivantes qui ont été détectées?
Tout d'abord, je suis le mainteneur de PHP_CodeSniffer, donc je suis clairement biaisé dans ce domaine. Mais j'ai également travaillé sur de grandes bases de code au cours de mes 10 années en tant que dev PHP dev, donc j'espère pouvoir apporter des raisons concrètes pour lesquelles les normes de codage sont une bonne chose. Je pourrais écrire une série de blogs sur ce sujet, mais je vais juste vous donner une petite histoire sur la façon dont PHP_CodeSniffer a vu le jour afin que vous puissiez comprendre le problème que l'outil a résolu pour moi.
J'ai travaillé sur quelques grands projets CMS. Le premier avait un tas de code derrière lui et une équipe de développement relativement petite. Nous n'avions pas de normes. Mais nous n'avons eu aucun vrai problème. L'équipe était petite et est restée ensemble pendant un bon moment. Nous nous sommes habitués l'un à l'autre.
Ensuite, nous avons construit un nouveau CMS. Nous avons recommencé avec seulement quelques développeurs. Je faisais alors partie d'une équipe de seulement deux développeurs. Encore une fois, les normes de codage ne nous ont posé aucun problème. Moi et l'autre développeur venions du même milieu et avions déjà établi quelques directives que nous avons suivies. Nous n'avions pas besoin de PHPCS à l'époque.
Mais cette équipe a développé un développeur à la fois et a finalement atteint 12 développeurs à temps plein et un certain nombre sont allés et viennent. Certains provenaient de l'ancien CMS et d'autres de l'extérieur de l'entreprise. Tous avaient des antécédents différents et une approche différente du développement. Il était évident qui avait écrit quel code parce que les styles étaient si différents. Chaque fois que vous travaillez sur quelque chose de complexe, vous devez d'abord vous adapter à leur style, car ce n'est tout simplement pas la façon dont vous avez l'habitude de voir le code. C'est comme lire Shakespeare pour la première fois. Vous devez vous y habituer avant de pouvoir lire à votre rythme naturel.
Pour les développeurs, ce temps supplémentaire pour s'arrêter et trouver un autre style de codage n'est qu'un pur temps perdu. C'est l'occasion pour une idée de s'échapper pendant que vous êtes embourbé avec l'espacement, l'indentation et la position du support. À la fin de la journée, ces choses n'ont pas d'importance. Mais laissez-moi vous dire, ils importent beaucoup s'ils poussent les développeurs à interrompre leur flux. Nous avions donc besoin d'un moyen de les faire sortir du chemin et de laisser les développeurs faire ce qu'ils font le mieux.
En même temps, nous creusions beaucoup plus sur JavaScript. Une nouvelle langue où le style était généralement jeté par la fenêtre. Le code a été copié/collé à partir des sites d'exemple et écrasé ensemble. En apprenant à développer du code complexe dans un nouveau langage, il était logique de trouver un moyen de rendre notre JS similaire à notre PHP. Nous pouvons le minimiser plus tard, mais nous devions pouvoir basculer rapidement entre les langues, encore une fois pour garder notre flux.
PHP_CodeSniffer est donc né pour cela. Il aide les développeurs à travailler sur le même style de codage pour éliminer complètement le formatage et les autres problèmes liés aux appâts enflammés. Il vous permet de traiter votre JS comme votre PHP dans une certaine mesure. Je l'utilise pour détecter des odeurs spécifiques au produit comme des chaînes non traduites ou des développeurs n'utilisant pas notre propre code d'inclusion de classe. J'utilise également pour des odeurs spécifiques à la langue, comme s’assurer que la virgule JS qui tue IE ne soit pas laissée autour. Vous pouvez l’utiliser pour ce que vous voulez. Elle est livrée avec des tas de reniflements faciles à fusionner ensemble à l'aide du fichier de règles XML . Vous pouvez également écrire le vôtre. Vous pouvez intégrer des outils tiers pour en faire un guichet unique pour l'analyse de code statique. Vous pouvez être aussi sérieux au sujet des normes et le code sent comme vous le souhaitez.
PHP_CodeSniffer, comme tout outil de développement, devrait fonctionner pour vous. Vous ne travaillez pas pour ça. S'il génère trop d'erreurs dont vous vous souciez peu, personnalisez la norme pour supprimer celles dont vous ne voulez pas ou transformez les erreurs en avertissements. Mais si mon histoire ressemble à quelque chose que vous vivez ou pourriez traverser à l'avenir, cela vaut la peine d'examiner de près PHP_CodeSniffer pour voir si cela peut vous aider.
J'espère que cela vous aide, vous et d'autres, à comprendre pourquoi les normes de codage sont vraiment importantes pour certains projets et développeurs. Ce n'est pas une question de détail. Il s'agit de supprimer le style de codage de la liste des choses qui font perdre le focus aux développeurs.
Avoir des conventions de style de codage est une bonne idée, car cela aide les développeurs à ne pas se laisser distraire par du code écrit dans un style différent lorsqu'ils travaillent sur du code qu'ils n'ont pas écrit. Cela rendra votre base de code superficiellement plus propre. C'est génial si vous pouvez l'automatiser, mais il n'est généralement pas nécessaire de parcourir de grandes longueurs pour se conformer (sauf si le style actuel est terrible ). Si vous avez déjà une norme suffisante, respectez-la.
L'odeur du code est quelque chose de différent cependant: ce sont (un ensemble de) symptômes qui peuvent indiquer un problème plus profond avec le code. Les exemples sont la complexité cyclomatique, les noms de méthode longs, les grandes classes, les noms non descriptifs, le code en double, etc. Ceci est généralement beaucoup plus problématique, car cela peut nuire à la maintenabilité de votre code. Vous devez certainement résoudre ces problèmes.
PHP CodeSniffer semble être principalement développé pour vérifier les conventions de style, pas l'odeur de code. Si vous pouvez l'utiliser pour aider à appliquer les conventions de style, tant mieux. Mais attention, cela n'améliorera pas sensiblement la base de votre code . Vous voudrez faire des révisions manuelles pour y parvenir.
Si vous souhaitez l'utiliser pour vérifier si vous vous conformez à votre norme actuelle , cela semble possible, voir la réponse à la question "Je ne ' t d'accord avec vos normes de codage! Puis-je faire appliquer PHP_CodeSniffer par moi-même? " dans leur FAQ .
Comptez sur moi parmi ceux qui évangélisent CodeSniffer. Après avoir été très sceptique pendant des années, je l'utilise maintenant sur tous les projets sur lesquels je travaille. Pourquoi?
Comme l'ont dit Grace Hopper et/ou Andrew Tanenbaum,
Ce qui est merveilleux avec les normes, c'est que vous avez tellement de choix.
De même, c'est presque toujours une mauvaise idée ™ pour créer votre propre norme de codage; en créer un assez complet pour couvrir tout votre code est difficile , et, plus important encore, il ne sera pas du goût de la prochaine personne de maintenir votre code, qui tentera d '"améliorer" votre standard afin qu'il convienne à son style de codage de longue date. L'adoption d'un standard extérieur approprié, que ce soit Zend ou PEAR ou Kohana ou JoeBobBriggsAndHisFifthCousin, vous permet de vous concentrer sur le le contenu plutôt que le formatage . Mieux encore, des outils comme PHP CodeSniffer prend en charge le standard "tout juste sorti de l'étain" ou ceux qui l'ont précédé ont presque certainement implémenté le support en tant qu'add-on.
Mélanger des normes de codage avec du code existant non écrit dans cette norme vous donnera des ajustements, à moins que vous n'adoptiez deux règles simples et complémentaires.
Excluez les fichiers antérieurs à votre adoption de la norme de codage de la vérification, via le
--ignoreoption de ligne de commande ou paramètres de fichier de configuration équivalents. Mais, lorsque vous modifiez une partie d'un fichier source, mettez à jour le fichier entier pour qu'il soit conforme à la norme que vous avez choisie.
Je viens de a écrit un nouveau blog à propos de ce genre de chose.
Il y a beaucoup de cas qui nécessitent un jugement humain, et CodeSniffer n'en a pas.
Crochets cohérents, l'indentation améliore le code. Manque d'espace après des virgules dans l'appel de fonction? Peut probablement être pardonné, mais c'est ERREUR selon CodeSniffer.
À mon humble avis, il y a beaucoup trop d'erreurs signalées par CS. Même les projets qui semblent avoir du code soigné peuvent facilement rencontrer des milliers de problèmes CS. Il devient rapidement fatigant et presque impossible de résoudre tous ces problèmes, en particulier lorsqu'il s'agit d'un mélange de vrais problèmes et de bêtises obsessionnelles-compulsives - les deux étant également souvent marqués comme ERREURS .
Il vaut peut-être mieux ignorer CS et passer du temps sur les améliorations réelles du code (en termes de conception, d'algorithmes) plutôt que simplement des changements d'espace et de commentaires complètement superficiels (la fonction 1 ligne isAlpha a-t-elle vraiment besoin de 8 lignes de Oui, si vous demandez CS).
Le CS peut trop facilement devenir un outil de polissage de l'étron.
C'est définitivement une bonne chose. Nous exécutons le nôtre à partir d'un hook SVN afin que tout le code doive passer le standard de la maison (une modification de PEAR) avant de pouvoir être validé (ce fut l'une des meilleures décisions que j'ai jamais prises).
Bien sûr, cela fonctionne mieux pour un nouveau projet, où il n'y a pas beaucoup de code hérité à convertir vers le nouveau standard. Une solution consiste à modifier votre hook de pré-validation SVN pour exécuter uniquement de nouveaux ajouts au codeniffer et ignorer les modifications. Vous pouvez le faire en ajoutant la ligne:
$SVNLOOK changed "$REPOS" -t "$TXN" | grep "^A.*\.php " > /dev/null || exit 0
Cela quittera le script de hook s'il n'y a pas de nouveau code PHP à analyser. Par conséquent, tous les nouveaux fichiers devront respecter la norme et vous pouvez mettre le code hérité à la norme dans votre propre temps.
Notez que si vous utilisez Eclipse ou Zend IDE vous pouvez bénéficier d'outils automatiques qui rendent le respect d'une norme moins coûteux. Vous pouvez également utiliser un outil d'intégration continue comme Hudson ou PHPUndercontrol.
- PDT est un éditeur sympa pour PHP
- PDT-Tools sont des plugins pour PDT avec un outil de formatage automatique
- DTLK (Dynamic Toolkit Library) peut être utilisé pour lancer certains scripts externes afin de vérifier vos fichiers.
Vous pouvez également jeter un œil à PHP Checkstyle qui je pense est plus facile à configurer (avertissement: j'ai travaillé dessus)
Certains autres outils sont répertoriés sur la page "documentation" du site Web.
CodeSniffer est une excellente chose à implémenter, mais vous devez savoir comment l'utiliser. Sauf si vous devez respecter une norme de codage donnée parce que vous soumettez votre travail à un projet externe, vous êtes libre de définir complètement vos propres normes de codage.
PHP CodeSniffer devrait vous faciliter la tâche, car il existe déjà de nombreux reniflements de code unique que vous pouvez inclure dans votre propre définition standard de codage et que vous n'avez pas besoin de les écrire à partir de zéro. En explorant les possibilités des codesniffers existants, vous pourriez finir par écrire une extension pour un sniff existant ou un sniff par vous-même, si vous en ressentez le besoin.
Si vous souhaitez commencer avec CodeSniffer, la première étape consiste à récupérer un ensemble de reniflements qui ressemblent complètement à vos normes de codage actuelles et à vérifier les erreurs et avertissements qui en résultent. N'appliquez pas l'une des normes prédéfinies, car cela entraînera très probablement trop d'erreurs avec trop peu d'avantages si elles sont corrigées. Par exemple, si vous n'utilisez pas PHPDoc pour générer une documentation, il serait inutile de remplir toutes les erreurs de codesniffer concernant les balises et les commentaires PHPDoc manquants.
Fournissez-vous des packages PEAR pour la distribution publique via PEAR/PECL? Si tel est le cas, vous voudrez probablement vous en tenir aux conventions PEAR).
Sinon, je ne vois pas que cela vaille la peine du grand refactor. Le plus important est de convenir d'une norme de codage pour votre équipe ... ne doit pas nécessairement être la norme de PEAR ... assurez-vous simplement qu'une convention standard est appliquée.
Par exemple, je suis fan de la
function foo () {
format vs la norme PEAR standard ..
function foo ()
{
En fin de compte, ne vous inquiétez pas trop de se conformer à leur norme si cela va être une tonne de travail, surtout si vous ne mettez pas les packages sur PECL.