Estándares de Codificación

Por Carlos Nacianceno, @igormx

Algunos lo llaman Coding by convention (codificación por convención) o simplemente Coding Standards  (estándares de codificación), es un paradigma de programación que busca reducir el número de decisiones que el desarrollador tiene que tomar al momento de escribir su código.

Todos sabemos qué reglas tiene PHP respecto las variables, funciones, clases, etc. Así, si una variable no cumple con esas reglas sería variable inválida y PHP lanzaría un error al ejecutar el script. Ahora dentro de la validez hay un gran número de posibilidades para nombrar una variable; por ejemplo, el resultado de un query puede ser $queryResult, $QueryResult, $queryresult, etc; el optar siempre por una forma de escribir el nombre de la variable sería seguir un estándar de codificación. Y no sólo las variables, también aplica para funciones, métodos, clases, identación, posición de las llaves, cantidad de caracteres por línea de código, entre otros.

En realidad, no se busca limitar al programador en su creatividad sino que hacen que el codificar se vuelva más sencillo incluso se puede volver intuitivo, pues la forma en la que se define cada parte del código es utilizada por todos los programadores del proyecto, así el estándar se comparte y se aprende más rápido, facilitando la lectura y escritura de código.

Los estándares de codificación, como ya dijimos, son utilizados en proyectos tanto públicos como privados. Zend Framework, por ejemplo, tiene sus estándares los cuales se basan en los de PEAR y estos a su vez en los de Horde . Y no sólo Zend Framework , sino casi todos los Frameworks PHP y otros proyectos Open Source tienen estándares.

Usando PHP Code Sniffer

En PEAR desde hace tiempo, existe una herramienta que nos permite “olfatear” los estándares, llamada PHP_CodeSniffer que busca violaciones de los estándares en archivos PHP, Javascript y HTML. Esto es muy útil ya que nos ayuda a mantener nuestro código limpio, consistente y también puede ayudar a evitar algunos errores de semántica.

Para instalar PHP CodeSniffer, se requiere de PEAR, que está presente en casi todas las instalaciones PHP.

pear install PHP_CodeSniffer

Una vez instalada esta herramienta ya podemos ejecutarla con el comando phpcs en archivos y proyectos completos, con un número muy grande de opciones.

Ahora vamos a mostrar un par de ejemplos de uso básico de PHP_CodeSniffer

Sniffing de un archivo

Revisemos primero un archivo concreto, usando el estándar de Zend, y omitiendo los Warnings (-n)

phpcs –standard=Zend -n evaluaciones/library/Crud/Forma/Status.php
FILE: …DefaultWorkspace7/evaluaciones/library/Crud/Forma/Status.php
——————————————————————————–
FOUND 4 ERROR(S) AFFECTING 4 LINE(S)
——————————————————————————–
9 | ERROR | No space found after comma in function call
10 | ERROR | No space found after comma in function call
11 | ERROR | No space found after comma in function call
16 | ERROR | A closing tag is not permitted at the end of a PHP file
——————————————————————————–

Nos entrega un reporte indicándonos cuáles fueron las violaciones y en qué línea ocurrieron. Las violaciones al estándar encontradas en el programa son referentes a las comas en los parámetros de las funciones y que tenemos presente el tag de cierre en el archivo.

Sniffing de un proyecto

Revisamos un proyecto o directorio completo, el estándar a probar será Zend (que esta basado en PEAR(que esta basado en Horde)) para no ver una lista de todos los archivos agregamos la opción –report=summary; además volvemos a suprimir los warnings y vemos un resumen de los tipos de violaciones más comunes.

phpcs –standard=Zend –report=summary -sn evaluaciones/

PHP CODE SNIFFER REPORT SUMMARY
——————————————————————————–
FILE ERRORS
——————————————————————————–
…e7/evaluaciones/application/controllers/CategoriasController.php 2
…/evaluaciones/application/controllers/DificultadesController.php 2
…kspace7/evaluaciones/application/controllers/IndexController.php 1
…space7/evaluaciones/application/controllers/StatusController.php 2
…tWorkspace7/evaluaciones/application/views/helpers/Paginador.php 8
…orkspace7/evaluaciones/library/Crud/Controlador/Accion.php 44
…tWorkspace7/evaluaciones/library/Crud/Forma/Categorias.php 3
…orkspace7/evaluaciones/library/Crud/Forma/Dificultades.php 3
…faultWorkspace7/evaluaciones/Crud/Forma/Status.php 4
…ultWorkspace7/evaluaciones/Crud/Modelo/Default.php 11
…aultWorkspace7/evaluaciones/Crud/Modelo/Mapper.php 6
…Zend/workspaces/DefaultWorkspace7/evaluaciones/public/estilo.css 14
…/Zend/workspaces/DefaultWorkspace7/evaluaciones/public/index.php 8
——————————————————————————–
A TOTAL OF 108 ERROR(S) WERE FOUND IN 13 FILE(S)
——————————————————————————–

PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
——————————————————————————–
SOURCE COUNT
——————————————————————————–
Generic.WhiteSpace.DisallowTabIndent 56
PEAR.ControlStructures.ControlSignature 26
PEAR.Functions.FunctionCallArgumentSpacing 13
PEAR.Functions.FunctionCallSignature 8
Zend.NamingConventions.ValidVariableName 3
Zend.Files.ClosingTag 1
PEAR.Classes.ClassDeclaration 1
——————————————————————————–
A TOTAL OF 108 SNIFF VIOLATION(S) WERE FOUND IN 7 SOURCE(S)
——————————————————————————–

Ahora me doy cuenta que, gran parte de las violaciones del estándar es por usar tabs para indentar código en vez de usar espacios como lo requiere mi estándar.

PHP_CodeSniffer tiene muchas opciones al momento de ejecutar, tantas que incluso te permite crear tus propios estándares , esto para que luego tu puedas implementarlo en tus proyectos tanto públicos como privados y revisarlos con la misma herramienta.