Clean code o código limpio

El arte del código limpio: El poder de los nombres significativos 

El clean code (o código limpio) es una práctica de programación que se basa en escribir código claro, legible y fácil de mantener. Consta de normas sobre cómo escribir código. Entre ellas encontramos: reglas de estilo como: evitar redundancias, mantener las funciones y métodos en pocas líneas y escribir comentarios sólo cuando sea necesario, entre otras.

Una de estas reglas es cuidar la nomenclatura de nuestro código para variables, funciones, clases…etc. La idea es usar nombres correctos para no depender de una documentación o comentario que ensucien el código y que además, llevaría un mantenimiento extra. Con esta serie de reglas de código limpio, deberemos de poder leer el código fácilmente, como si se tratase de un libro para programadores. Elegir los nombres correctos puede tomar tiempo, pero merece la pena, ya que en realidad estaremos agilizando el trabajo.

principios más importantes del clean code o código limpio

Hay una serie de reglas de estilo que nos ayudarán a tener nombres significativos en nuestro código. Algunas de las que pensamos más importantes son las siguientes:

Usar nombres auto descriptivos

Recordemos que lo que queremos es prescindir de comentarios adicionales que añadan complejidad a la lectura de nuestro código. Para ello, lo primero y más importante es que los nombres que usemos se expliquen por si solos. Si al leer el nombre de nuestra variable ya sabemos para qué se utiliza, no hará falta ningún comentario adicional. Simple ¿no?

Por ejemplo, supongamos que queremos almacenar los días que lleva un usuario sin modificaciones. En nuestro código lo tenemos en la siguiente variable: int d;

Pero podemos encontrar un nombre mucho mejor, que nos explique cuál es el valor que almacena, por ejemplo: int daysSinceLastModification;

De esta forma, no será necesario comentar qué guarda o para qué sirve una variable. Cuando volvamos a esa parte del código después de un tiempo podremos simplemente leerlo y lo entenderemos. Lo mismo aplica para las funciones y las clases, no es igual de claro user.GetThem() que user.GetAllBooks().

Clean code o código limpio

Evitar la desinformación en los nombres

Si en el punto anterior hemos conseguido darle un valor y significado a nuestros nombres, el siguiente paso es que no debemos confundir al lector.

Como programadores debemos evitar las abreviaciones en los nombres. Éstas pueden parecer una buena idea al momento de escribir el código, pero a la larga provocarán confusiones. Si por ejemplo tenemos la variable addressDt, la parte de Dt puede ser confusa ¿Qué significa Dt?¿DataType?¿DateTime? Si además estamos trabajando con ADO.NET ¿será de DataTable?

Para no crear este tipo de confusiones, debemos evadir las abreviaciones y escribir la variable completa: addressDetail.

Además, en este ejemplo hemos podido comprobar que hay ciertas palabras claves que significan algo más para los programadores, como es el caso de DataTable. Evitemos agregar palabras clave como DataTable o List si la variable no es de verdad un DataTable o una List.

Escribir nombres que puedas pronunciar

Como humanos, estamos estrechamente relacionados con el uso del lenguaje. Gran parte de nuestro cerebro se dedica al concepto de este. Por ende, lo más lógico es que los nombres que creemos en nuestro código sean fácilmente pronunciables tal y como lo son las palabras en nuestro lenguaje.

Vamos con un ejemplo. Supongamos que tenemos una variable que almacena la cantidad que tenemos de un producto. Si a esta la llamamos prodQnty lo más seguro es que terminemos leyéndola algo así como “prodty” o “prodcunty”. De modo que, si estamos teniendo un debate sobre esa parte del código con nuestro compañero de equipo, no podremos pronunciar esta variable sin parecer idiotas.

Sin embargo, si cambiamos el nombre de la variable a productQuantity, ahora sí podemos tener una conversación seria sobre los cambios que queramos aplicar a ese código.

Usar nombres buscables

A lo largo del día, como programadores, vamos a hacer muchas búsquedas en el código. No te das cuenta de lo mal elegido que está un nombre hasta que la búsqueda que estás intentando no te facilita el encontrar esa función, variable… etc.

Y es que, la aplicación promedia terminará siendo un océano de letras tarde o temprano. Por esa razón, buscar el nombre exacto de la variable que queremos, si no está bien definido, puede ser como buscar una aguja en un pajar.

No será lo mismo buscar WORK_DAYS_PER_WEEK que el número 5 en el código.

La longitud de un nombre deberá ir directamente relacionada con el ámbito de este. Si tenemos un Enum con los días laborables de la semana, imagínate el lío que puede ser buscar los casos de uso mediante la letra “d”. Sin embargo, podremos terminar muchísimo antes si le hemos puesto un nombre como WorkingDays.

En el otro extremo, para una variable numérica que nos va a ayudar a iterar un bucle for, no hay problema con nombrarla con la letra ‘i’ ya que se utilizará en un contexto muy reducido. Además, en este caso es ya una convención global en programación.

Nombres de métodos y clases

Los nombres para las clases y los métodos tienen una convención dentro de la serie de reglas de código limpio. Estas son bastante sencillas:

  • Para los nombres de las clases usaremos sustantivos o frases de nombre tal como pueden ser Customer, Product, UserAccount. El nombre de una clase no debe contener un verbo.
  • Los métodos, por otro lado, deben tener nombres de verbos. Unos nombres de métodos perfectos para las clases anteriores podrían ser: getName, hasStock y signOut.

Una palabra por concepto

Elige una palabra para cada concepto y comprométete con ella. Debes mantener la coherencia de cada acción o concepto abstracto que tengas en tu código.

Por ejemplo, supongamos que tenemos una clase User, a la que, como ya sabemos poner nombres perfectos de métodos, le agregamos el método saveNewPassword. Hasta aquí todo genial. Más tarde, trabajamos en una clase Bank y nos hace falta agregar un método para almacenar movimientos en las cuentas del banco. Ahora optamos por llamar al método writeMovement.

Este tipo de inconsistencia es lo que debemos evitar. Alguien que venga de trabajar con nuestra clase User y pase a usar la clase Bank, esperará que el método correcto sea saveMovement. Por ello, para cada concepto del código, debemos elegir una palabra y mantenerla.

Usar nombres de dominios de soluciones

Los lectores de tu código serán más programadores. Lo mejor que puedes hacer como programador al elegir nombres, es utilizar términos técnicos. Así, tanto los lectores como tú os podréis ahorrar tiempo en explicaciones.

Utiliza nombres de términos informáticos, patrones de diseño, algoritmos y demás. Un programador que esté familiarizado con el patrón de diseño Visitor, al leer el nombre AccountVisitor, ya se hace una idea de lo que se va a encontrar dentro de esa clase.

Usar nombres de dominios de problemas

Si no existe un término en la programación para lo que estés haciendo, utiliza el nombre del problema que resuelve la parte en la que estás trabajando.

De este modo, si otro compañero tiene que trabajar con este código, podrá preguntar sobre el dominio a alguien que esté familiarizado con este. Y si no, al menos se habrá acotado esa parte del código a un problema en concreto, quitando algo de esfuerzo a la hora de entenderlo.

Conclusiones 

Hemos podido repasar los puntos más importantes a la hora de elegir nombres en nuestro código y también hemos podido comprobar de primera mano lo que unos simples cambios pueden ayudar a la legibilidad y el mantenimiento del mismo. 

Según pongamos en práctica estas reglas, comprobaremos que escribir código limpio es un ejercicio que requiere de disciplina, constancia y espíritu crítico. Pero, merece la pena por todos los beneficios que nos ofrece al escribir y mantener una aplicación. 

Por último, me gustaría hacer una mención especial a una práctica que creo, nos beneficiará como desarrolladores. Esta es nada menos que la regla de oro de los boy scouts americanos: deja el campamento más limpio de lo que lo encontraste. Es decir, cuando vayas a tocar código ya existente, echa un vistazo alrededor y si ves que un nombre puede mejorar, no dudes en ponerte a ello. 

José Álvarez – Software Developer at Itequia