Hoy comienzo una serie de artículos en donde enunciaré algunas de los principios básicos a los que nos deberíamos acostumbrar si queremos escribir código limpio. Como una imagen vale más que mil palabras os dejo la idea que subyace tras este concepto:

No obstante, si queréis una definición algo más profunda de lo que significa código limpio mi favorita es la que propuso Ward Cunningham:

You know you are working on clean code when each routine you read turns out to be pretty much what you expected. You can call it beautiful code when the code also makes it look like the language was made for the problem.

Es decir, escribir código limpio es conseguir que cada parte de nuestro programa haga exactamente lo que esperamos. Ni más ni menos.

Por tanto, en esta serie de artículos pretendo abordar algunos de los principios o reglas que podemos adoptar si queremos mejorar la calidad de nuestro código. Muchas de ellas están extraídas del libro Clean Code: A Handbook of Agile Software Craftmanship así cómo de un par de libros acerca de patrones de diseño que he leído en los últimos meses.

Así que, ¡comencemos!

Nombrado

Dice un “dicho” que uno de los principales problemas a los que nos enfrentamos cuando desarrollamos es escoger nombres adecuados para nuestros ficheros, clases y variables. No es para menos. Escoger un buen nombre para cada elemento de nuestras aplicaciones es necesario si queremos conseguir que éstos sean fáciles de leer y no nos quebremos la cabeza tratando de averiguar lo que significa una variable o lo que hace una función cuando tengamos que volver a ellos.

🆒 Regla general: legible mejor que inteligente

Todas las recomendaciones que voy a enumerar a continuación podrían resumirse en la siguiente regla:

Prefiere nombrar las cosas de modo legible a hacerlo de modo inteligente

Entendiendo “inteligente” por ese afán de demostrarnos a nosotros mismos lo astutos que somos al nombrar las cosas: bien escogiendo nombres originales bien buscando abreviaciones que meses después nos traerán de cabeza para encontrar su significado.

Sé amable con tu “yo del futuro” o con tus compañeros de equipo y pon las cosas fáciles a la persona que tendrá que mantener tu código.

Usa nombres que revelen intención

El nombre de cualquier elemento de nuestro programa, ya sea archivo, clase o función debería revelarnos de forma directa el motivo de su existencia.

De este modo, es recomendable evitar el uso de expresiones como let n = 'My name' en aras de conseguir expresiones más cortas. Cuando más adelante alguien se encuentre con esa variable n le estarás obligando a retroceder para averiguar su significado, haciendo el proceso mucho más complicado que de haber empleado un nombre descriptivo como name o fullname .

Por supuesto, ésto también se aplica a esa costumbre tan nuestra de buscar nombres originales para variables como por ejemplo fn para expresar un fullname o pWP para nombrar una variable que almacena una persona con su factura ( personWithPet ).

Usa nombres que aporten una distinción clara

Éste es uno de los principios más evidentes pero que sin embargo creo que más cuesta aplicar durante el proceso de escribir código. ¿Quién no se ha encontrado a menudo escribiendo nombres de funciones muy similares? Por ejemplo:

findUsers
findUsersData
findUserAccount

Este tipo de situaciones suelen obligarnos a tener que re-averiguar la distinción entre estos métodos cada vez que queremos emplearlos lo cual evita que podamos enfocarnos en lo que realmente importan.

Por tanto, lo deseable es acostumbrarnos a escoger nombres que nos permitan identificar de forma rápida y sin lugar a confusión el elemento al que representan.

Usa nombres que posteriormente puedas buscar

Esto permitirá posteriormente localizar mucho más rápido aquello que necesitemos. Por tanto, evita nombres de un solo caracter (salvo que sean métodos de una sola línea en los que estemos empleando funciones como filter , map o reduce) y nombres impronunciables que obliguen a hacer un esfuerzo extra para recordarlos.

Evita los números mágicos

Es decir, trata de evitar expresiones como:

if (users.length > 10) {

ya que provocan que el código pierda significa obligándonos a investigar el significado de esos valores. En el ejemplo anterior, 10 es un número mágico (no en el buen sentido del término) ya que resulta importante para la lógica del código pero carece de valor semántico.

Una mejor forma de reescribir el código anterior sería:

const maxAssistants = 10;...if (users.length > maxAssistants) {

ya que nos permite entender el objeto de la condición.

Otro problema de los números mágicos es que si los empleamos en distintas partes del código con el mismo significado será más difícil mantener la aplicación ya que, si cambian de valor, tendremos que irlos buscando uno a uno en vez de modificar una vez su valor en la constante que los representan.

Evita los prefijos y sufijos innecesarios

Puede parecer mentira pero no hace mucho me encontré con código que contenía variables nombradas del tipo nameString , peopleArray … Pese a que antiguamente esto era “relativamente” necesario debido a la ausencia de tipado en los lenguajes de programación y/o a la carencia de editores potentes, actualmente es algo redudante.

Lo que quiero decir es, suponiendo que hemos escogido correctamente el nombre name para una variable que almacena el nombre de alguien creo que es fácil esperar que dentro habrá un string sin necesidad de “ayudarnos” (por muy útil que sea) del tipado.

Esta regla también es, en general, aplicable a los nombres de nuestros ficheros si bien algunas convenciones o “frameworks” nos invitan a emplear sufijos como por ejemplo ContactController o UserInterface .

Escoge un nombre para cada concepto

Éste es de otros principios que parecen evidentes pero que en la práctica es difícil respetar. Lo que quiere expresar que si estamos empleando la palabra fetch para nombrar métodos que recuperan datos de algún sitio ( fetchUsers , fetchBills …) siempre empleemos ese término para esa clase de métodos y, por supuesto, no lo usemos en otros contextos (por ejemplo, para generar un PDF, fetchPDF).

Emplea “Solution Domain Names”

Es decir, acostúmbrate a usar términos que pertenecen al vocabulario del desarrollo como por ejemplo el nombre de los patrones de diseño que emplees o el de conceptos que tienen un significado conocido dentro de comunidad.

De este modo, al desarrollador que se encuentre más adelante con el código le será mucho más sencillo entender el propósito de aquello que escribiste.

Emplea “Problem Domain Names”

Toda aplicación se enmarca dentro de un cierto problema que hay que resolver y es casi seguro que este problema tendrá sus propios conceptos y términos. Úsalos. No busques sinónimos porque te suenen mejor e incluso plantéate la necesidad de traducirlos al inglés.

Esto nos permitirá mantener nuestro código mucho más fácil que si tenemos que recordar lo que significaba un término dentro del problema que estamos resolviendo y reducirá la “fricción” de incorporar a nuevos desarrolladores al equipo, ya que la correspondencia entre lo que se quiere resolver y el código será directa.

Conclusiones

He decidido empezar por el nombrado porque creo que para mejorar basta con emplear el sentido común y es algo que tanto un “junior” como un programador “senior” pueden empezar a poner en práctica desde el primer día.

Asimismo, los beneficios de acostumbrarnos a nombrar “bien” las cosas los notaremos mejor desde el primer día y nos permitirán a la larga tener un código mucho más mantenible. Que a fin de cuentas es de lo que quiero tratar en estos artículos.

Apóyame en Patreon

Gracias a: Alex Fuentes.

¿Quieres recibir más artículos como este?

Si te ha gustado este artículo te animo a que te suscribas a la newsletter que envío cada domingo con publicaciones similares a esta y más contenido recomendado: 👇👇👇