3 tips para escribir código limpio, legible y mantenible

Cuando estamos empezando nuestras carreras, creemos que nos la vamos a pasar escribiendo un montón de código, y si bien eso no es falso, tampoco es 100% verdadero. La verdad es que además de escribir vamos a leer. Vamos a leer mucho. Quizás vamos a leer más de lo que escribimos. Por esa razón, es importante que tu código sea limpio, legible y mantenible.

Código declarativo

El código declarativo es el que dice, que hay que hacer, pero no como hacerlo. Sé que esto no significa mucho todavía, así que vamos a verlo más en detalle con algunos ejemplos.

El código declarativo se basa en la abstracción. Es decir, en vez de ejecutar cierta lógica, ejecutamos una función que realiza esa lógica o creamos una variable con un nombre descriptivo para esa lógica. De esta forma, hacemos que todo sea entendible en la primera lectura.

En caso de ser necesario, siempre podemos ir a ver qué hace la función para poder entender mejor esa lógica, pero en principio lo único que necesitamos saber es qué hace, y no como lo hace.

Veamos este código…

if (user.age >= 18 && user.products.length > 0) {
  doSomething();
}

Si bien podemos leerlo y entenderlo, sería mucho más fácil de entender si tomaramos un paradigma más declarativo…

const isAdult = user.age >= 18;
const isClient = user.products.length > 0;

if (isAdult && isClient) {
  doSomething();
}

De esta forma podemos entender el big picture rápidamente y después, solo si es necesario, leer el resto.

Comentarios

Los comentarios son un tema sensible entre los programadores. Hay muchos fans de comentar todo y muchos fans de no comentar nada.

A nosotros nos gusta usar un approach híbrido. Por default, no comentamos nada. Creemos que es mejor hacer código auto-descriptible. Sin embargo, hay ciertos casos en los que aparecen valores arbitrarios o cosas que simplemente tienen que estar ahí y que, por más de que tratemos de usar buenos nombres en variables y funciones, simplemente es difícil de entender por alguna razón en específico. En estos casos agregamos un pequeño comentario explicando la razón de ese valor arbitrario o la razón por la cual el código está escrito de la forma que está escrito.

// Acá explicaríamos el porqué le estamos restando un año al usuario,
// algo que a simple vista no tiene mucho sentido.
userAge -= 1;

Por otro lado, es complemente correcto asumir que nuestro código va a ser leído por programadores. Partiendo de esa premisa, los comentarios que describen exactamente lo que hace el código, se vuelven completamente inútiles y redundantes. Un ejemplo:

// Si el usuario tiene más de 18 años, ejecutar la función doSomething()
if (userAge >= 18) {
  doSomething();
}

Naming conventions

La forma de nombrar variables y funciones dependerá de cada equipo. Cualquier forma está bien siempre que se mantenga a lo largo de toda la codebase. Sin embargo, hay algunos puntos que siempre me parece interesante tener en cuenta.

Abreviaciones consistentes

Abreviar es una buena forma de mantener las cosas cortas, pero puede volverse un descontrol.

Para que eso no pase, hay 2 cosas a tener en cuenta:

• Que la abreviación tenga sentido y se entienda muy fácilmente a que se refiere.
• Que la abreviación sea consistente. Si hay 2 variables con la misma palabra abreviada, las 2 abreviaciones deberían ser iguales para evitar confusiones.

Evitar doble negativo

El doble negativo se refiere a cuando el nombre de una variable está en negativo y se lo usa en una condición con un signo negador adelante.

Algo así:

const isNotAdult = userAge < 18;

if (!isNotAdult) {
  doSomething();
}

Suele pasar bastante y hace que se vuelva más complejo de entender.

Simplemente con darle una vuelta, todo sería mucho más fácil de leer y entender.

const isAdult = userAge >= 18;

if (isAdult) {
  doSomething();
}

Conclusión

Todos estos detalles apuntan a reducir la complejidad a la hora de leer y entender un código. Y si el código es más fácil de entender, también es más fácil de mantener.

Por último, es recomendable hablar estas cosas con el equipo y ponerse todos de acuerdo para seguir las mismas convenciones.