Clean Code – Consejos para ser mejor desarrollador WordPress (II)

WordPress

¿Sabías que sólo somos tres personas aquí en Nelio? Y aún así nuestras entradas molan, ¿eh? ¡Es gracias a nuestro nuevo plugin, Nelio Content! ¿Por qué no lo usas tú también?

Hace ya unos cuantos meses compartí contigo mi opinión sobre “El programador pragmático: de aficionado a maestro”, un libro que, como te decía entonces, incluye consejos y buenas prácticas de programación. Si todavía no has leído el libro, permíteme que vuelva a recomendártelo, porque es muy ameno e instructivo. Sea como fuere, en esa entrada también te comenté que tenía un segundo libro en la estantería esperando su momento, Clean Code,  ¿recuerdas? Pues bien, el caso es que ya me lo he leído y me ha gustado incluso más que “El programador pragmático”. Así que, si te parece bien, repitamos el formato de la entrada anterior y echemos un vistazo al libro y a las que, en mi opinión, son sus mejores partes.

Un vistazo al libro

Clean Code parte de una premisa muy interesante: “incluso los códigos malos funcionan”. Es decir, incluso si el código no está limpio y ordenado, si es caótico y difícil de comprender, si está escrito de manera pobre, nada de ello tiene por qué tener un impacto negativo en su funcionamiento; el código puede funcionar como se supone que debe funcionar. Ahora bien, coincidirás conmigo y con el autor del libro, el bueno de Robert C. “tío Bob” Martin, que tener que lidiar con un engendro como el descrito es un gran problema, ¿verdad? 😱

Los componentes de software juegan un papel importantísimo en cualquier empresa. Si el su código fuente no está limpio y ordenado 😵, puede hundir cualquier empresa, porque la cantidad de horas y recursos brutales que tendrá que invertir en él cada vez que tenga que cambiarlo, adaptarlo o corregirlo será brutal. Es por ello que este libro te enseña a escribir código limpio y a detectar código mejorable.

El libro se divide en tres partes. En primer lugar, describe los principios, patrones y buenas prácticas que hacen que un código fuente sea limpio. En la segunda parte dispones de un montón de casos de estudio (cada vez más complejos) donde se parte de un mal código que se va puliendo poco a poco, hasta que se llega a una solución elegante y eficiente. La última parte es un recopilatorio de consejos para detectar cuándo un fragmento se puede mejorar y cómo hacerlo. En otras palabras, es un apartado de referencia donde te enseñan a leer, escribir e incluso anhelar el prometido “Clean Code”.

Tal y como nos prometen en la contraportada del libro, si lo lees con cariño, lo estudias y, sobretodo, decides aplicar las enseñanzas que incluye, el resultado final es que sabrás:

  • Cómo diferenciar un código malo de un código bueno
  • Cómo escribir buen código y cómo transformar código malo en código bueno
  • Cómo crear buenos nombres, buenas funciones, buenas clases…
  • Cómo formatear y organizar el código para maximizar su inteligibilidad
  • Cómo implementar la gestión de errores sin esconder la lógica del código tras esa gestión
  • Cómo crear tests unitarios y aplicar los principios del TDD (desarrollo orientado por tests)

No está nada mal, ¿verdad?

Los capítulos del libro son los siguientes:

  1. Código Limpio. Una introducción a la diferencia entre el código ininteligible y el código limpio. Especialmente divertida es la imagen con la que abre el capítulo:

    La única métrica real sobre la calidad del código fuente: el número de WTF (“pero qué coj…nes”) por minuto. Fuente.
  2. Nombres con significado. Consejos variados para conseguir que nuestras funciones, variables, clases… en definitiva, todos los componentes de nuestro código sean inteligibles y autoexplicativos.
  3. Funciones. Consejos sobre la forma que deben tener las funciones: breves, atómicas, sencillas, con pocos parámetros, sin efectos secundarios…
  4. Comentarios. Básicamente, se dedica un capítulo entero a decirte que no los uses. El porqué lo encontrarás en el libro 🤓.
  5. Formato. Consejos para organizar el código (espaciado, indentación, etc). Este podrías llegar a obviarlo, porque en WordPress tenemos unas guías de estilo muy buenas que ya tratan el tema.
  6. Objetos y estructuras de datos. Otra vez, consejos y principios variados sobre la abstracción de datos y reducir (o eliminar) el acoplamiento.
  7. Gestión de errores. Un gran capítulo con consejos para añadir la gestión de errores en nuestro código. En esencia, aquí se discute una triste realidad: el control de errores es algo secundario a la funcionalidad principal que queremos resolver y, por lo tanto, meter ese control en nuestro código lo “ensucia”. Pues bien, aquí te explican cómo hacerlo de manera limpia.
  8. Límites. Uno de los problemas más duros a los que nos enfrentamos los programadores (y esto es especialmente cierto en WordPress) es la dependencia de librerías o servicios externos; si estos cambian, las cosas pueden dejar de funcionar. En este capítulo se identifican diferentes escenarios en los que podemos tener problemas de compatibilidad al depender de terceras partes y se dan consejos para eliminar o minimizar su impacto.
  9. Tests unitarios. Poco voy a mencionar de este capítulo, cuya temática ya hemos tratado anteriormente en el blog.
  10. Clases. Si bien los primeros compases del libro se centran en las partes más básicas del código (funciones y estructuras de datos), un buen código requiere de una buena organización. Por ello, el libro dedica este capítulo y el siguiente a hablar de la organización del código. En este en concreto se centra en la programación orientad a objetos y en sus clases, dando algunos consejos básicos sobre tamaño y responsabilidades.
  11. Sistemas. Capítulo más abstracto que el anterior, pues intenta explicar el concepto de sistema, la interacción entre los diferentes componentes, los problemas que pueden surgir… Aún con todo, es muy recomendable echarle un vistazo, especialmente si lidias con bases de código fuente grandes (¿alguien ha dicho “Core de WordPress“?)
  12. Diseño emergente. En este capítulo dan cuatro directrices que hay que seguir a la hora de escribir código. Si las sigues, y consideras todos los consejos anteriores, el código resultante será limpio. Por orden de importancia, las reglas son:
    • Tu código pasa todos los tests que has definido de antemano.
    • Tu código no tiene duplicidades.
    • Tu código expresa claramente la intención del programador.
    • Tu código utiliza el número mínimo de clases y métodos posible.
  13. Concurrencia. Un capítulo dedicado a hablar de los problemas típicos en sistemas concurrentes y cómo atacarlos.
  14. Refinamiento sucesivo. Caso de estudio en el que se empieza con un mal código y se va refinando y mejorando poco a poco.
  15. El interior de jUnit. Otro ejemplo práctico. En este caso, se meten en las entrañas de jUnit y muestran cómo se podría mejorar.
  16. Refactorizando SerialDate. Y, finalmente, otro caso de estudio más. En este caso, partimos de lo que el autor denomina un “buen código”, pero aún así es capaz de encontrarle múltiples fallos y puntos de mejora basándose, sobretodo, en los principios del capítulo 12.
  17. Pistas y heurísticos. Una fantástica recopilación de pistas para identificar componentes del código que claramente están mal o tienen muchos números de estarlo y que, por lo tanto, habría que corregir para mejorar el código. Este capítulo no se trata de leerlo y ya; debes usarlo como referencia y tenerlo a mano cuando te dispongas a mejorar un código existente (que tranquilamente puede ser la función que escribiste ayer por la tarde). ¡En mi opinión, este capítulo no tiene precio!

Los 3 mejores consejos del libro

El libro es una auténtica gozada. Está muy bien escrito y dispone de un montón de truquitos que ojalá todos conociéramos e intentáramos aplicar… (aunque, oye, leer el libro y proponérselo ya es un primer paso, ¿no?). Supongo que después del repaso a todos los capítulos y promesas del libro te has quedado con ganas de leer más, pero tal y como te he prometido, no voy a dejar que te vayas sin repasar los 3 consejos estrella del libro (según mi opinión).

🥉 Bronce. “Los comentarios no sirven para arreglar un mal código”.

Tal y como comenta Martin, “uno de los motivos por los cuales escribimos código es porque (sabemos que) el código es malo“. Piénsalo un par de segundos: acabas de escribir un nuevo módulo y, bueno, funciona, pero es un poco confuso y está un poco desordenado… ¡qué rayos! Desordenado no, es desastroso. Así que lo miras y dices… “bueno, voy a comentar el código para que se entienda”. ¡No! Debes arreglar este desaguisado.

El código jamás debería necesitar un comentario para ser comprensible; lo debería ser por sí mismo. Y es que los comentarios suponen, en general, más problemas de los que arreglan. Por un lado, el comentario puede estar desactualizado y no corresponderse con el código. Además, aún cuando ese no sea el caso, actualizar el código implica la necesidad de actualizar el comentario, con lo que debes trabajar el doble. Y, por otro lado, los comentarios pueden acabar siendo un estorbo.

Por ejemplo, mira este fragmento:

// Comprobar que el empleado puede recibir la bonificación
if ( empleado.ranking >= SENIOR && empleado.proyectos.contains( 'NelioContent' ) )

¿No sería mucho mejor este otro?

if ( empleado.puedeRecibirLaBonificacion() )

Lo único que hemos hecho ha sido “materializar” el comentario como parte del código, convirtiéndolo en una función que invocamos dentro del if. Y sí, amigo, tomando decisiones de este tipo es como mejoramos nuestro código.

Evidentemente, hay casos en los que los comentarios sí son necesarios (incluso obligados). Por ejemplo, si estás preparando una API, es evidente que tiene que estar bien documentada para que sus futuros clientes la puedan usar. A fin de cuentas, se supone que no tiene por qué tener acceso al código fuente… Pero, incluso en estos casos, los nombres de las funciones y sus parámetros deberían ser autoexplicativos.

🥈 Plata. “Las funciones no deben tener efectos secundarios”.

“Los efectos secundarios son mentiras; tu función promete hacer una cosa, pero hace otras ocultas“. No podrías estar más de acuerdo con esta afirmación. Cuando una función depende de y manipula variables globales, sus ejecuciones son erráticas y se generan dependencias muy, muy difíciles de analizar y corregir. Y esto es algo que pasa muchísimo en el Core de WordPress: dependemos muy fuertemente de variables y objetos globales que se pasan de un lado a otro… lo cual, en mi opinión, entorpece y dificulta la comprensión del código. Es por ello que evitar los efectos secundarios es un consejo que debemos tener especialmente en cuenta en el mundo WordPress.

Otro efecto secundario habitual es tener parámetros de entrada salida en una función (cosa que podemos hacer en PHP y, por lo tanto, en WordPress). En este caso, llamar a una función y que el resultado de esa llamada cambie alguno de los parámetros es poco intuitivo. En general, todos suponemos que los parámetros de las funciones son de entrada y punto; para saber que hay algún parámetro que puede cambiar después de invocar la función deberíamos leer la documentación y… bueno, acabamos de decir que, en general, los comentarios deberían no ser necesarios, ¿no?

En fin, para que te hagas una idea concreta del problema del que hablamos, considera el ejemplo que ponen en el libro:

public class UserValidator {
  ...
  public boolean checkPassword(String username, String password) {
    User user = UserGateway.findByName(username);
    if (user != User.NULL) {
      if (user.hasPassword(password)) {
        Session.initialize();
        return true;
      }
    }
    return false;
  }
  ...
}

¿Eres capaz de ver dónde está el efecto secundario? ¡Efectivamente! Está en la inicialización de la sesión. El usuario está invocando una función que se llama “comprobar contraseña”, así que uno espera que esta función compruebe si el usuario y la contraseña son válidos y punto. Así que ¿por qué se está inicializando una sesión como parte del proceso? 🤷 ¡Yo qué sé! Si ese es el funcionamiento que queríamos, quizás un nombre como este hubiera sido más adecuado: checkPasswordAndInitializeSession. Y precisamente este ejemplo nos lleva al oro de mi ranking personal del libro Clean Code…

🥇 Oro. “Nombres con sentido”.

Los nombres lo son todo en el software. A fin de cuentas, la programación no es más que describir el sistema que estamos implementando en un lenguaje formal que pueda interpretar el ordenador. Y, como lenguaje que es, los conceptos y nombres están por todas partes: funciones, variables, argumentos, clases, ficheros, directorios… ¡todo tiene nombre! Así que te lanzo la siguiente pregunta: ¿dedicas el tiempo necesario a poner nombres adecuados? ¿O pones lo primero que se te pasa por la cabeza?

La verdad es que todo el capítulo 2 me parece un acierto absoluto y está lleno de consejos útiles. Creo que todo programador debería leerlo, estudiarlo y aplicarlo en su día a día. Entre los diferentes consejos que incluye tenemos:

  1. Usa nombres claros que revelen la intención. ¿Cuántas veces te has encontrado con variables cortitas como, por ejemplo, d, seguidas de un comentario explicativo tipo “el tiempo que ha pasado en días”? A veces los programadores somos perezosos… ¡y no deberíamos serlo! Mejor llámala elapsedTimeInDays, o daysSinceCreation o fileAgeInDays.; lo que quieras, pero que sea útil y acarree significado.
  2. Evita confundir a la gente. Los nombres deben dar información real y no engañar. Por ejemplo, si tenemos un conjunto de cuentas, no la llames accountList a no ser que esté implementado realmente como una lista, porque lo normal es que un programador asuma que si la variable incluye la palabra List en su nombre es que se ha implementado usando esa estructura de datos. Un nombre más sencillo como accounts sea probablemente mejor.
  3. Haz distinciones con sentido. Muchas veces, por cuestiones del lenguaje, no podemos usar la palabra que queremos para nombrar una cosa. Por ejemplo, podemos querer llamar una variable class y no podemos porque es una palabra reservada, así que optamos por klass o clazz. Eso es una mala idea. Otro ejemplo muy común, tenemos dos variables del mismo tipo, así que las llamamos igual con un numerito detrás: string1 y string2. ¿No sería mejor llamarlas source y destination? ¡Si es que sin tener código delante en un caso no tienes ni idea de para qué se van a usar esos strings y en el otro sí!
  4. Los nombres tienen que poder pronunciarse. El ejemplo que pone en el libro es hilarante: en una empresa tenían una variable llamada genymdhms (fecha de generación gen, por año y, mes m, día d, hora h, minuto m y segundo s). Cuando los programadores hablaban entre ellos sobre el código, ¿cómo hacían referencia a esa variable? “Oye, la gen-y-eme-de-hache-eme-ese del fichero tal…” ¡Un desastre! Con lo fácil que hubiera sido llamarla generationTimestamp
  5. Los métodos deberían ser verbos o sintagmas verbales. Ejemplos los podemos encontrar directamente en WordPress, con métodos y funciones del tipo have_posts, get_the_author o is_single.
  6. Sé consistente y usa el mismo concepto siempre. Muchas veces hay sinónimos que podríamos usar indistintamente: fetch, get o retrieve; delete, remove o trash. Intenta usar siempre el mismo concepto y no vayas cambiando entre uno y otro, porque la uniformidad ayuda a que el código sea fácil de entender y reduce la carga mental del programador.
  7. y muchos, muchos más ejemplos.

Mi opinión final

En definitiva, Clean Code es un libro entretenido y educativo. Te recomiendo que lo adquieras ya y lo añadas a tu librería personal. Los consejos y trucos que contiene son muy valiosos. Además, después de leerlo te deja con las ganas de aplicar los principios que en él se explican… y créeme cuando te digo que el salto de calidad que hay entre el código que escribes antes y después de leer este libro es enorme.

¿Lo has leído ya? ¿Qué te pareció? ¿Tienes alguna recomendación otra para mí?

Imagen destacada de Joel Filipe vía Unsplash.

FlojaNo está malBienMuy bien¡Impecable! (1 votos, promedio: 5,00 de 5)
Cargando…

por

Lidera el análisis y diseño de nuestros servicios, así como el servicio de soporte a los usuarios. Es Doctor en Computación por la UPC y siempre ha estado interesado en una gran variedad de áreas, incluyendo el modelado conceptual, la realidad virtual y la impresión digital en 3D. Contribuye muy activamente en la comunidad WordPress, habiendo participado en meetups, seminarios y en la WCEU.

3 comentarios en “Clean Code – Consejos para ser mejor desarrollador WordPress (II)

  1. ¡Ey, este post me ha sido de gran ayuda! Andaba buscando información para empezar un nuevo wordpress, pero sin saltarme ningún paso o detalle importante, y creo que en este artículo has reunido todas las pautas que me preocupaban, haha. Me voy a quedar con este blog como referencia para futuras dudas parecidas, que las habrá (: WordPress es un mundo tan amplio que nunca termino de aprender.

    Un abrazo y felicidades por vuestra labor (:

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

He leído y acepto la Política de privacidad de Nelio Software.

Al marcar la casilla de aceptación estás dando tu legítimo consentimiento para que tu información personal se almacene en SiteGround y sea usada por Nelio Software con el propósito único de publicar aquí este comentario. Contáctanos para corregir, limitar, eliminar o acceder a tu información.