Código mas mantenible (I) - Legibilidad

Es asombroso como con un poco de cuidado y esfuerzo logramos que nuestro código sea mucho más legible. También es asombroso la poca importancia que le damos en general a este tema. Siempre, a veces por culpa de la complejidad innecesaria o por presión de fechas de entrega cercanas, perdemos el norte y solo nos importa que el código funcione, sin tener en cuenta que si no se entiende será inmantenible, incluso, y sobre todo, para nosotros mismos, cuando tengamos que venir a modificarlo...mañana.

La legibilidad de un código fuente se logra básicamente cuando se cumplen las siguientes propiedades:

1. El código es claro y fácil de leer.
2. La intención detrás de cada sentencia es obvia.
3. La longitud del código es minimal.

Veamos cada una en detalle:

1 - Claro y fácil de leer

Para que un código sea claro y fácil de leer debe tener principalmente nombres específicos y descriptivos, tanto de funciones, constructores como de variables y clases.

No se puede dejar de subrayar la importancia de este punto. Una correcta elección de nombres implica además que el programador conoce el tema sobre el cual esta trabajando, por otro lado no poder encontrar un término especifico a menudo implica que el programador no sabe que tiene que hacer exactamente o no termina de entender la relación con el problema.

A veces es dificil encontrar un nombre adecuado y exige tiempo, pero es tiempo bien invertido porque se están definiendo al nombrarlos a los conceptos centrales del sistema en desarrollo.

En la primera versión de XP existía una práctica llamada Metáfora (que fue dejada de lado en XP 2nd edition, de Kent Beck) que trataba de encontrar un concepto globalizador de todo el sistema. Justamente, una metáfora, que sirviera para describir el sistema como un todo con un concepto tomado desde un significado distinto o de un contexto diferente. Bueno, esta práctica facilitaba grandemente la elección de nombres porque implicaba elegir un pequeño sub-mundo de la realidad, un contexto con su vocabulario especifico y relacionarlo conceptualmente con la solución del sistema en cuestión.
Así, por ejemplo, si estamos creando un sistema de inventario de mercaderías y aplicamos una metafora de Hotel, cada habitación se corresponde con un deposito y en ese caso las materias que se almacenan en el depósito serían los "pasajeros", de ahi extraeriamos los nombres, por ejemplo para decir que una mercaderia sale podriamos usar: mercaderia.checkout() y asi.

2 - Intencion Obvia

Un escritor de novelas o cuentos escribe de manera obvia cuando su intención es revelada sin vueltas, sin ninguna indirección o bifurcación de logica, ni frases agregadas, y sobre todo, sin complejidad innecesaria.

Un punto importante a aclarar es la audiencia para la cual la intención tiene que ser obvia. Esto debe quedar bien claro:

"Trabajamos para hacer mantenible el sistema para el siguiente programador que tendrá que programar modificaciones sobre este código."

Nuestra audiencia es, por lo tanto, técnica y pensando en ellos debemos programar, no para que el código sea entendido por un funcional, un usuario final o nuestro gerente.

Debemos desarrollar código cuya intención sea clara y obvia para un programador, por ello está perfectamente bien utilizar términos técnicos para nombrar una variable o agregar datos de un Pattern especifico que estamos implementando en el nombre de la clase.

Ej: SyntaxCorrectorVisitor, CustomerSearchCommand

3 - Longitud de código es minimal

El concepto es que sea la menor cantidad de código posible que permita solucionar el problema respetando a la vez el punto 1 y 2.

Si la longitud del código es demasiado larga, aun cuando los nombres estén bien elegidos y cada sentencia en si sea corta y obvia su intención, será difícil de leer. Esto es asi porque es bien sabido que no podemos prestar atención a varias cosas a la vez, y tener que comprender un texto largo es mucho más complejo que varios pequeños textos cortos.

Además, una cadena larga de sentencias casi seguro conlleva mezclar sentencias de distinto nivel de abstracción, poniendo juntos conceptos abstractos con detalles muy específicos. Es como si un escritor en medio de una frase en una novela de acción sobre la guerra divagara de todo el proceso de como fabricar un arma, desde crear la aleacion de metal del arma hasta como construir la bala.

Por último, un código extenso aumenta la probabilidad de que dupliquemos parte del código casi sin darnos cuenta y hace mucho más difícil encontrar errores, debuggear y armar tests de unidad (hay que testear demasiadas cosas y hasta el tests más pequeño va a necesitar de mucha configuración y código de startup).

En sintesis, vale la pena hacer el esfuerzo de que nuestro código sea más legible, sobre todo porque, como deciamos más arriba, el siguiente programador que tendrá que leerlo será.....nosotros mismos.