¿Qué tan útil es PHP CodeSniffer? Code Standards Enforcement en general?

code-smell standards-compliance

Question

Estoy incursionando con la idea de configurar PHP CodeSniffer en nuestro servidor de integración continua en un esfuerzo por mejorar la calidad de nuestro código base. Después de leer la documentación, estoy muy entusiasmado con la idea de normalizar y aplicar nuestros estándares de codificación. Sin embargo, me pregunto acerca de la mejora real de nuestro producto. Soy muy consciente de que el sniffer solo detecta violaciones a un estándar de codificación definido, pero ¿qué tipo de beneficios proporciona una base de código limpia y consistente? ¿Vale la pena el trabajo adicional para refactorizar un proyecto con 100k + líneas de código para cumplir con el estándar PEAR?

Para aquellos que no están familiarizados con PHP CodeSniffer o code-smell en general, aquí hay un ejemplo de salida:

ARCHIVO: /path/to/code/myfile.php
ENCONTRADO 5 ERROR (S) AFECTANDO 2 LÍNEA (S)
-
2 | ERROR | Falta el archivo doc comment
20 | ERROR | Las palabras clave de PHP deben ser minúsculas; esperado "falso" pero encontrado "FALSO"
47 | ERROR | Línea no sangrada correctamente; espera 4 espacios, pero encontró 1
51 | ERROR | Falta la función del comentario del documento
88 | ERROR | Línea no sangrada correctamente; esperaba 9 espacios, pero encontró 6

Estrictamente hablando, el usuario / cliente no notaría ninguna diferencia en un producto que se refactivó para cumplir con los estándares, pero me pregunto si hay otros beneficios ocultos

En este momento, nuestro código no es descuidado e intentamos seguir nuestros propios estándares personales que, en su mayor parte, se derivan de los Estándares de codificación de Pear pero un ojo entrenado puede detectar las diferencias.

Entonces mi pregunta es cuánto mejoran la calidad de un producto. ¿Qué tipo de beneficios latentes resultan de esto?

¿Estoy siendo obsesivo-compulsivo con mi deseo de acercar nuestro producto a un conjunto de estándares? ¿Valdría la pena que? De ser así, ¿qué tipo de estrategia utilizó para implementar el detector de códigos y corregir las violaciones posteriores que se detectaron?

Answer 1

¿Está proporcionando paquetes de PEAR para distribución pública a través de PEAR / PECL? Si es así, probablemente quieras apegarte a las convenciones de PEAR.

De lo contrario, no puedo ver que valga la pena el gran refactor. Lo más importante es acordar un estándar de codificación para su equipo ... no tiene por qué ser el estándar de PEAR ... solo asegúrese de que se cumpla con alguna convención estándar.

Por ejemplo, soy un fanático de

function foo () {

formato vs el estándar PEAR ..

function foo ()
{

En pocas palabras, no se preocupe demasiado por cumplir con su estándar si va a ser un montón de trabajo, especialmente si no está poniendo los paquetes en PECL.

Answer 2

CodeSniffer es una gran aplicación, pero debes saber cómo usarlo. A menos que tenga que cumplir con un estándar de codificación dado porque está enviando su trabajo a algún proyecto externo, puede definir completamente sus propios estándares de codificación.

PHP CodeSniffer debería hacer esto muy fácil para usted, porque ya hay muchos sniffs de código único que puede incluir en su propia definición de codificación estándar y no necesita escribirlos desde cero. Al explorar las posibilidades de los Codesniffers existentes, es posible que termine escribiendo una extensión de un sniff existente o uno solo, si siente la necesidad.

Si desea comenzar con CodeSniffer, el primer paso sería obtener un conjunto de olores que se parezcan por completo a los estándares de codificación actuales y verificar los errores y advertencias resultantes. No aplique uno de los estándares predefinidos, ya que esto probablemente resultará en demasiados errores con muy pocos beneficios si se solucionan. Por ejemplo, si no usa PHPDoc para generar una documentación, no sería útil cumplir con todos los errores de codesniffer sobre las etiquetas y comentarios faltantes de PHPDoc.

Answer 3

Cuenten entre los que evangelizan a CodeSniffer. Después de ser muy escéptico durante años, ahora lo uso en cada proyecto en el que estoy trabajando. ¿Por qué?

Como lo dijo Grace Hopper y / o Andrew Tanenbaum,

Lo maravilloso de los estándares es que tienes tantos para elegir.

Del mismo modo, casi siempre es una Idea Mala crear su propio estándar de codificación; crear uno lo suficientemente completo como para cubrir todo su código es difícil , y, lo que es más importante, no será del agrado de la siguiente persona mantener su código, quien tratará de "mejorar" su estándar para que se adapte a su largo estilo de codificación sostenida. Adoptar un estándar externo apropiado , ya sea Zend, PEAR o Kohana o JoeBobBriggsAndHisFifthCousin, le permite concentrarse en el contenido en lugar del formato . Mejor aún, las herramientas como PHP CodeSniffer o bien admiten el estándar "recién salido de la lata" o los que ya han llegado antes casi seguramente han implementado el soporte como un complemento.

Mezclar estándares de codificación con código existente no escrito en ese estándar le dará ajustes, a menos que adopte dos reglas simples y complementarias.

Excluya los archivos que son anteriores a la adopción de la norma de codificación para que no se comprueben, a través de la opción --ignore línea de comando o configuración de archivo de configuración equivalente. Pero, cuando modifique cualquier parte de un archivo fuente, actualice el archivo completo para cumplir con su estándar elegido.

Acabo de escribir una nueva publicación en el blog sobre este tipo de cosas.

Answer 4

En primer lugar, soy el mantenedor de PHP_CodeSniffer, por lo que estoy claramente predispuesto en esta área. Pero también he trabajado en grandes bases de código en mis 10 años como desarrollador de PHP, así que espero poder aportar algunas razones concretas sobre por qué los estándares de codificación son algo bueno. Podría escribir una serie de blogs sobre este tema, pero les daré una pequeña historia sobre cómo surgió PHP_CodeSniffer para que puedan entender el problema que la herramienta resolvió para mí.

He trabajado en algunos grandes proyectos de CMS. El primero tenía un montón de código detrás y un equipo de desarrollo relativamente pequeño. No teníamos estándares. Pero no tuvimos problemas reales. El equipo era pequeño y permanecieron juntos durante bastante tiempo. Nos acostumbramos el uno al otro.

Luego creamos un nuevo CMS. Empezamos de cero con solo un par de desarrolladores. Yo era entonces parte de un equipo de solo dos desarrolladores. Una vez más, los estándares de codificación no nos causaron ningún problema. Yo y el otro desarrollador vinimos del mismo origen y ya habíamos establecido algunas pautas que seguimos. No necesitábamos PHPCS en ese momento.

Pero ese equipo creció como desarrollador a la vez y eventualmente llegó a 12 desarrolladores a tiempo completo y muchos vinieron y se fueron. Algunos vinieron del viejo CMS y algunos vinieron de fuera de la compañía. Todos tenían diferentes antecedentes y un enfoque diferente del desarrollo. Era obvio quién escribió qué código porque los estilos eran muy diferentes. Cada vez que trabajabas en algo complejo, primero tenías que adaptarte a su estilo porque simplemente no era la forma en que estabas acostumbrado a ver el código. Es como leer a Shakespeare por primera vez. Debes acostumbrarte antes de poder leer a tu ritmo natural.

Para los desarrolladores, ese tiempo extra para tener que detenerse y descubrir otro estilo de codificación es simplemente tiempo perdido. Es una oportunidad para que una idea se escape mientras estás empantanado con el espaciado, la sangría y la posición del bracket. Al final del día, estas cosas simplemente no importan. Pero déjame decirte, importan mucho si están causando que los desarrolladores rompan su flujo. Por lo tanto, necesitábamos una forma de hacer que se apartaran del camino y dejar que los desarrolladores hicieran lo que mejor saben hacer.

Al mismo tiempo, estábamos profundizando en JavaScript mucho más. Un nuevo lenguaje donde el estilo generalmente se tiraba por la ventana. El código se copió / pegó de sitios de ejemplo y se mezclaron. Al aprender a desarrollar código complejo en un nuevo idioma, tiene sentido encontrar una manera de hacer que nuestro JS se vea similar a nuestro PHP. Podemos minimizarlo más tarde, pero necesitamos poder cambiar entre idiomas rápidamente para mantener nuestro flujo.

Entonces PHP_CodeSniffer nació para hacer eso. Ayuda a los desarrolladores a trabajar con el mismo estilo de codificación para que el formateo y otros problemas con el cebo de llama se salgan completamente del camino. Le permite tratar su JS como su PHP hasta cierto punto. Lo uso para detectar olores específicos del producto, como cadenas no traducidas o desarrolladores que no usan nuestro código de inclusión de clases adecuado. También lo uso para olores específicos del lenguaje, como asegurarme de que la coma JS que mata IE no quede atrás. Puedes usarlo para lo que quieras. Viene con montones de olores que son fáciles de combinar utilizando el archivo de conjunto de reglas XML . También puedes escribir el tuyo. Puede integrar herramientas de terceros para que sea una ventanilla única para el análisis de código estático. Puede ser tan serio acerca de los estándares y el código huele a su gusto.

PHP_CodeSniffer, como cualquier herramienta de desarrollo, debería funcionar para usted. Usted no trabaja para eso. Si produce demasiados errores que no le interesan, personalice el estándar para eliminar los que no desea o convierta los errores en advertencias. Pero si mi historia suena como algo que está pasando o podría pasar en el futuro, vale la pena echar un vistazo a PHP_CodeSniffer para ver si puede ayudarlo.

Espero que eso les ayude a ustedes, y a otros, a entender por qué los estándares de codificación son realmente importantes para algunos proyectos y desarrolladores. No se trata de los detalles. Se trata de eliminar el estilo de codificación de la lista de cosas que hace que los desarrolladores pierdan el enfoque.

Answer 5

Esto definitivamente es algo bueno. Ejecutamos el nuestro desde un enlace SVN para que todo el código tenga que pasar el estándar de la casa (una modificación de PEAR) antes de que pueda comprometerse (esta fue una de las mejores decisiones que tomé).

Por supuesto, esto funciona mejor para un nuevo proyecto, donde no hay un montón de código heredado para convertir al nuevo estándar. Una forma de evitar esto es modificar el enlace de precompilación de SVN para que solo ejecute nuevas adiciones al códigoniffer e ignore las modificaciones. Puedes hacer esto agregando la línea:

$SVNLOOK changed "$REPOS" -t "$TXN" | grep "^A.*/.php " > /dev/null || exit 0

Esto saldrá del script hook si no hay un nuevo código PHP para analizar. Por lo tanto, todos los archivos nuevos deberán obedecer el estándar y usted podrá llevar el código heredado al estándar en su propio tiempo.

Answer 6

Hay muchos casos que requieren juicio humano, y CodeSniffer no tiene uno.

Los corchetes consistentes, la sangría mejoran el código. ¿Falta de espacio después de las comas en la llamada de función? Probablemente se puede perdonar, pero eso es ERROR según CodeSniffer.

En mi humilde opinión, hay demasiados errores informados por CS. Incluso los proyectos que parecen tener un código perfecto pueden toparse fácilmente con miles de problemas de CS. Rápidamente se vuelve agotador y casi imposible resolver todos esos problemas, especialmente cuando se trata de una mezcla de problemas reales y tonterías obsesivo-compulsivas, ambos igualmente marcados como ERRORES .

Puede que sea mejor ignorar CS y gastar tiempo en mejoras reales del código (en términos de diseño, algoritmos) en lugar de cambios de comentarios y espacios en blanco completamente superficiales (¿la función isAlpha 1 línea realmente necesita 8 líneas de comentarios? Sí, si tu preguntas CS).

CS puede convertirse demasiado fácilmente en una herramienta para pulir turd.

Answer 7

Tener una convención de estilo de codificación es una buena idea, ya que ayuda a los desarrolladores a no distraerse con un código escrito en un estilo diferente cuando trabajan con código que no escribieron. Hará que su código base sea superficialmente más limpio. Es genial si puedes automatizarlo, pero por lo general no es necesario hacer grandes esfuerzos para cumplirlo (a menos que el estilo actual sea terrible ). Si ya tiene un estándar lo suficientemente bueno, apéguese a él.

Sin embargo, el olor del código es algo diferente: es (un conjunto de) síntomas que pueden indicar un problema más profundo con el código. Los ejemplos son complejidad ciclomática, nombres largos de métodos, clases grandes, nombres no descriptivos, código duplicado, etc. Esto suele ser mucho más problemático, ya que puede dañar por completo el mantenimiento de su código. Definitivamente deberías resolver estos problemas.

PHP CodeSniffer parece ser desarrollado principalmente para verificar las convenciones de estilo, no el código de olor. Si puedes usarlo para ayudar a hacer cumplir las convenciones de estilo, genial. Pero ten en cuenta que no hará que tu código base sea sustancialmente mejor . Querrá hacer revisiones manuales para lograr eso.

Si desea usarlo para verificar si cumple con su estándar actual , que parece ser posible, consulte la respuesta a la pregunta "No estoy de acuerdo con sus estándares de codificación. ¿Puedo hacer que PHP_CodeSniffer haga cumplir el mío?" en sus preguntas frecuentes

Answer 8

Tenga en cuenta que si está utilizando Eclipse o Zend IDE, puede beneficiarse de herramientas automáticas que hacen que el respeto de un estándar sea menos costoso. También puede usar una herramienta de integración continua como Hudson o PHPUndercontrol.

• PDT es un genial editor para PHP
• PDT-Tools son algunos complementos para PDT con una herramienta de formateo automático
• DTLK (Dynamic Toolkit Library) se puede utilizar para iniciar algunas secuencias de comandos externas para comprobar sus archivos.

También puedes echarle un vistazo a PHP Checkstyle, que creo que es más fácil de configurar (descargo de responsabilidad: he trabajado en ello)

Algunas otras herramientas se enumeran en la página "documentación" del sitio web.