No debo crear código espagueti en WordPress

Vamos a ver por qué no debemos usar código espagueti en WordPress, pero antes de comenzar:

¿Qué es el código espagueti?

En este caso lo mejor es mostraros directamente la definición de Wikipedia:

El código espagueti es un término peyorativo para los programas de computación que tienen una estructura de control de flujo compleja e incomprensible. Su nombre deriva del hecho que este tipo de código parece asemejarse a un plato de espaguetis, es decir, un montón de hilos intrincados y anudados.

Tradicionalmente suele asociarse este estilo de programación con lenguajes básicos y antiguos, donde el flujo se controlaba mediante sentencias de control muy primitivas como goto y utilizando números de línea.

Pero, que levante la mano quién no ha realizado alguna vez código espagueti, yo desde luego no puedo levantar la mano y sobre todo si revisasemos ahora el código que escribía a finales de los 90… mejor sigamos avanzando.

Los estándares en WordPress

En nuestro código, ya sea una hoja de estilo, un tema o un plugin de WordPress, deberemos seguir una serie de estándares, en breve veremos el por qué:

Os recomiendo leeros todos los estándares, aunque vamos a utilizar chuleta, la chuleta se llama EditorConfig.

¿Qué es EditorConfig?

Pues para responde a esta pregunta nada mejor que la propia definición de su web:

EditorConfig ayuda a los desarrolladores a definir y mantener estilos de estándares de código consistentes entre diferentes editores e IDEs. El proyecto EditorConfig  consiste en un formato de archivo para definir estándares de código y una colección de plugins para los editores de texto que habilitan a dichos editores a leer el formato de archivo y adherirse a los estilos definidos. Los archivos de EditorConfig son fácilmente legibles y trabajan bien con los sistemas de control de versiones.

En resumen, un archivo .editorconfig que va en el raíz de nuestro proyecto y define diferentes aspectos de como debemos escribir el código.

¿Y cómo definimos uno para trabajar con WordPress?, bueno, no hace falta, ya está definido: .editorconfig de WordPress.

¿Y que hago ahora con ese archivo?, pues ponerlo en el raíz de tu proyecto (la carpeta principal) y usar un plugin en tu editor.

Yo actualmente utilizo Visual Studio Code, después de haber pasado por Eclipse, Sublime Text, Atom, Brackets y otros, y para todos he encontrado un plugin, extensión, etc., para habilitar dicha configuración, el que uso actualmente en VSC es EditorConfig for Visual Studio Code, pero seguramente encontrarás el adecuado para tu editor.

PHPcs, ¿qué es eso?

Otra herramienta imprescindible si utilizamos PHP (si sólo usamos CSS o javascript nos olvidaremos de esta parte) es PHPcs o PHP_CodeSniffer, que nos permite ir “mirando” nuestro código PHP y avisarnos de fallos, sugerirnos mejoras, etc., en base a los estándares que le hayamos definido. Yo utilizo la extensión vscode-phpcs, pero como en el caso anterior encontrarás la extensión adecuada para tu editor.

Para phpcs deberemos instalarlo en el sistema, ya sea mediante pear o con composer, encontrarás las instrucciones adecuadas a cada sistema e IDE sin mayor problema.

Una vez instalado y configurado con los estándares de WordPress, de los que tenemos el paquete adecuado disponible (WordPress Coding Standards for PHP_CodeSniffer), tendremos directamente en nuestro editor los fallos cometidos, sugerencias, etc., para que nuestro código se adhiera a los estándares especificados.

Visual Studio Code con phpcs

JSHint, ¿y esto?

JSHint es similar a PHPcs, es un linter que nos avisa de errores en nuestro código javascript, además de ofrecernos sugerencias de como debemos escribirlo según “las normas” que le dictemos en nuestra configuración general o en nuestra configuración específica del proyecto (archivo .jshintrc).

Y WordPress también nos proporciona dicho archivo para que usemos en nuestros proyectos y nuestro código se adhiera a los estándares mencionados.

Como en los casos anteriores, encontraréis la extensión adecuada para vuestro editor, yo utilizo VSCode JSHint.

¿Y con esto ya está?

Pues no, es sólo el inicio, en cuanto a extensiones, para facilitar las cosas os voy a enumerar algunas de las que yo utilizo con Visual Studio Code, además de las ya enumeradas anteriormente:

  • Alignment: Para alineaciones de textos, por ejemplo los espacios de una serie de variables hasta el signo igual.
  • ansible-autocomplete: Para el uso de Ansible, aprovisionamiento de servidores, creación de máquinas de pruebas, CI, etc.
  • Apache Conf: Resaltado de sintaxis de archivos de Apache.
  • Code Outline: Para mostrar un panel con la lista de variables, funciones y métodos del archivo abierto (desde Visual Studio Code también podemos navegar por el árbol con Ctrl/Cmd + May + O).
  • Docker: Resaltado de sintaxis de archivos Docker.
  • Easy LESS: Sintaxis LESS, a partir de los archivos LESS y cada vez que se guarda el archivo se genera el archivo CSS minimificado y con autoprefixer.
  • Git History: Para ver fácilmente nuestra historia del repositorio Git actual (Git viene integrado de maravilla con VSC).
  • IntelliSense for CSS class names: Sugerencias de autocompletado de clases CSS basadas en nuestro proyecto.
  • Jinja: Sintaxis para las plantillas python utilizadas con Ansible.
  • JSCS: Soporte de JSCS.
  • Ansible Syntax Highligting Extension: Otra extensión para archivos de Ansible, en este caso para la sintaxis.
  • minify for VS Code: Reducir el código CSS, JS y HTML. Principalmente lo uso para javascript ya que con CSS suelo utilizar LESS.
  • NGINX syntax: Igual que Apache Conf pero para Nginx.
  • PHP Debug Adapter: Realizar Debug del código PHP con XDebug.
  • Crane – PHP code-completion: Autocompletado de código PHP.
  • Project Manager: Para el cambio rápido entre diferentes proyectos.
  • Settings Sync: Una extensión imprescindible y de las primeras a instalar. Nos permite sincronizar las extensiones instaladas y nuestra configuración personalizada de VSC. Si realizo cambios en VSC en el PC, cuando abra VSC en el portátil me la sincronizará mediante un Gist privado de GitHub y lo tendré igual, o si reinstalo el ordenador, instalo esta extensión y me pondrá el entorno tal como lo tenía antes. Entre sus múltiples opciones tiene una muy interesante para trabajo en equipos con la que podemos compartir nuestra configuración con otros usuarios.
  • TODO Highlight: Personalizar totalmente el resaltado de nuestros TODOs, FIXME, y otras anotaciones a revisar en el código.
  • TODO Parser: Un parser de TODOs y demás anotaciones que definamos y poder verlas rápidamente agrupadas e ir directamente a las mismas.
  • Vagrant: Gestión de máquinas Vagrant.
  • vscode-icons: Un set de iconos diferente para VSC.
  • WakaTime: Para el servicio del mismo nombre y controlar el tiempo invertido en cada proyecto, por tipo de archivo, etc.
  • WordPress Snippet: Un conjunto de 2.884 funciones y 191 clases y constantes, para ayudarnos con los parámetros y nombres de las funciones de WordPress y ahorrarnos alguna visita a su codex.

Utilizo alguna más, pero quizás algo menos relacionadas con el desarrollo WordPress.

Pero volviendo a la pregunta ¿Y con esto ya está?, pues no, aún no está.

Deberemos saber utilizar la consola en nuestro equipo con Linux, OS X o Windows (Windows Subsystem for Linux), quizás también putty o Mosh, puede que alguna herramienta gráfica de Git como SourceTree, SVN si subimos código al repositorio de WordPress, utilizar Filezilla, tal vez VVV, Poedit, VirtualBox, sistema de BackUp para nuestros archivos, etc., etc.,

Ok, entonces si manejo todo esto ¿ya voy a realizar buen código?.

Pues no, todas estas herramientas te ayudarán en la creación de un buen código, pero NINGUNA te hará escribir buen código.

El último libro que he leído te podrá ayudar a crear un buen código (u otros similares), CREAR, estamos creando algo.

Se trata de Clean Code: A Handbook of Agile Software Craftsmanship de Robert C. Martin, descubierto gracias a una entrada de David Aguilera de Nelio SoftwareClean Code – Consejos para ser mejor desarrollador WordPress (II)

Clean Code

Tendremos que aprender a refactorizar nuestro código, a mantenerlo adecuadamente y volver sobre el mismo para mejorarlo de vez en cuando.

Invertir tiempo en crear los nombres adecuados de nuestras clases, métodos, variables, constantes y otras partes de nuestro código que a primera vista nos podrían parecer que carecen de importancia.

A comentar adecuadamente, o a no comentar si el código es lo suficientemente descriptivo como debe ser.

En definitiva, podríamos crear un libro sobre como escribir bien el código, aunque esa no es la intención de este artículo, pero vayamos a la cuestión principal de este artículo:

Por qué no debemos usar código espagueti en WordPress.

Motivos para escribir buen código

Si vamos al pie de página de la web de WordPress veremos que aparece CODE IS POETRY al igual que en muchas otras páginas del CMS.

¿No es una razón suficiente?, te voy a indicar algunas más:

  • Comenzamos con una cita de Robert C. Martin de Clean Code: “El campo @author de un Javadoc indica quiénes somos. Somos autores. Y los autores tienen lectores. De hecho, los autores son responsables de comunicarse correctamente con sus lectores. La próxima vez que escriba una línea de código, recuerde que es un autor y que escribe para que sus lectores juzguen su esfuerzo.”
  • El buen código se lee como un buen libro, sin necesidad de explicaciones.
  • El trabajo que dediquemos ahora a crear un buen código nos será ampliamente recompensado en un futuro cuando debamos modificarlo, mejorarlo o simplemente mantenerlo.
  • Aunque pensemos que nunca más vamos a tener que volver a tocar ese código, casi te podría afirmar que lo tendrás que modificar por algún motivo en un 90% de los casos y lo que hoy es evidente, mañana puede resultar un jeroglífico indescifrable, que curiosamente hemos creado nosotros mismos.
  • Si nos adherimos a los estándares, nuestro código será fácilmente legible, modificable y ampliable por cualquier otro programador.
  • Cuesta lo mismo escribir avia una vez que había una vez y aunque el lector nos entenderá de ambas maneras, cada una de las dos formas dirá algo diferente de nosotros.
  • Un programador senior se diferencia de uno junior en las soluciones que aporta y en como las aporta (su código), entre otras facultades.
  • Menos es más: que una función realice tres tareas no es mantenible a largo plazo. Una función realiza una función, valga la redundancia, pero es la mejor explicación que se le puede dar 😉
  • Y podríamos seguir con docenas, quizás cientos de razones más para escribir buen código, código limpio, pero os voy a dar una última fundamental.

Razón final para escribir buen código

Se podría resumir en una sola palabra: Tide.

Tide es un proyecto iniciado y liderado por XWP, una de las grande agencias que trabajan con WordPress y con grandes marcas (son de Australia).

Tide es soportado por GoogleAutomattic y WPEngine.

En la última State of the Word, Matt Mullenweg anunció la adopción del proyecto Tide por parte de WordPress.

Pero, ¿qué es Tide y que implica esto?

Tide se centra en el código limpio, los estándares de código y la compatibilidad del mismo con diferentes versiones de PHP y de WordPress.

Una de las herramientas que uiliiza Tide es pcpcs ¿os suena?, en su definición podemos leer: “Tide is a mechanism for executing PHPCS and storing the results of it in an API, the real work is done in the WordPress Coding Standards & PHPCompatibility standard projects”.

Seguro que os ha sonado algo eso de estándares del código de WordPress.

¿y qué implica esta definición?.

Pues sencillamente, que cuando esté totalmente integrado en el repositorio de WordPress, si tenemos un plugin en el mismo, nos indicará con que versiones de PHP es compatible, versiones de WordPress y calidad del código en base a los estándares.

La consecuencia es que si nuestro plugin y/o tema funciona correctamente, pero no tiene un código estándar de las directrices de WordPress, tendrá “menos estrellitas” o el sistema que elijan finalmente para la puntuación y quedará relegado a puestos inferiores.

Me parece una idea fantástica para que en todo momento sepamos si el plugin que estamos buscando va a funcionar correctamente con nuestra versión de WordPress, si además es compatible con la versión de PHP que tenemos instalada en el hosting y como colofón, si el código del mismo tiene la suficiente calidad.

Que no se diga que el código de WordPress es de baja calidad: Code is Poetry.

Ejemplo puntuación Tide del plugin Jetpack

Citas finales

Y con esto espero que tengáis alguna razón para mejorar un poco vuestro código, aunque solo sea poner bien las tabulaciones, nombres de variables…

Y voy a finalizar esta entrada (que ya va siendo hora, pensaréis), con un par de citas del libro de Robert C. Martin:

…La maestría se consigue de dos formas: conocimientos y trabajo. Debe adquirir el conocimiento de los principios, patrones, prácticas y heurística propios de un maestro, y dominar dichos conocimientos a través de la práctica.

Puedo enseñarle la teoría de montar en bicicleta. De hecho, los conceptos matemáticos clásicos son muy sencillos. Gravedad, fricción, velocidad angular, centro de masa, etc., se pueden demostrar en menos de una página repleta de ecuaciones. Con esas fórmulas, puedo demostrar que montar en bicicleta es práctico y proporcionarle los conocimientos necesarios para conseguirlo. Pero la primera vez que se monte en una bici se caerá al suelo.

El diseño de código no es diferente. Podríamos enumerar todos los principios del código limpio y confiar en que se encargue del resto (es decir, dejar que se cayera de la bici) pero entonces la pregunta sería qué clase de profesores somos y qué clase de alumno sería.

No. Así no funciona este libro.

Aprender a crear código limpio es complicado. Requiere algo más que conocer principios y patrones. Tiene que sudar. Debe practicarlo y fallar. Debe ver cómo otros practican y fallan. Debe observar cómo se caen y recuperan el paso. Debe ver cómo agonizan en cada decisión y el precio que pagan por tomar decisiones equivocadas…

 

…La mala noticia es que crear código limpio es como pintar un cuadro. Muchos sabemos si un cuadro se ha pintado bien o no, pero poder reconocer la calidad de una obra no significa que sepamos pintar. Por ello, reconocer código limpio no significa que sepamos cómo crearlo.

Para crearlo se requiere el uso disciplinado de miles de técnicas aplicadas mediante un detallado sentido de la “corrección”. Este sentido del código es la clave.

Algunos nacen con este sentido. Otros han de luchar para conseguirlo. No solo permite distinguir entre código correcto e incorrecto, sino que también muestra la estrategia para aplicar nuestra disciplina y transformar código incorrecto en código correcto.

Un programador sin este sentido puede reconocer el desastre cometido en un módulo pero no saber cómo solucionarlo. Un programador con este sentido verá las posibles opciones y elegirá la variante óptima para definir una secuencia de cambios.

En definitiva, un programador que cree código limpio es un artista que puede transformar un lienzo en blanco en un sistema de código elegante…