Clean Code Capítulo 2 Nombres con Sentido 1/2

A medida que escribimos código es inevitable enfrentarnos a la tarea que aunque parece trivial no lo es, de asignar nombre a una variable, clase, paquete, archivo etc. Cuando digo que no es trivial, quiero hacer énfasis a su importancia y a que al poner un nombre se debe hacer con responsabilidad y profesionalismo (lógica, coherencia y mucho sentido), puesto que estos nombres empezarán a dotar de sentido al código mismo, y de eso nos daremos cuenta al momento que otros programados lo lean o hasta nosotros mismos cuando con el tiempo debamos realizar mantenimiento sobre este. El autor de Clean Code sabe esto, por tal motivo nos proporciona una serie de reglas básicas para crear nombres correctos.

Usar nombre que revelen las intenciones: Cuántas veces hemos encontrado una variable con nombre así: int a; ¿Esto te dice algo?, ¿Sabes para qué sirve la variable a o que significado tiene?, precisamente de eso se trata esta regla, dotar de significado y sentido a través de su nombre, por ello el autor nos dice “El nombre de una variable, función o clase debe responder una serie de cuestiones básicas. Debe indicar por qué existe, qué hace, y cómo se usa”. Veamos un ejemplo tomado de Clean Code.

Incorrecto

public List<int[]> getThem(){
List<int[]> list1 = new ArrayList<int[]>();
for(int[] x : theList)
if(x[0] == 4)
  list1.add(x);
return list1;
}
Correcto
public List<int[]> getFlaggedCells(){
List<int[]> flaggedCells = new ArrayList<int[]>();
for(int[] cell : gameBoard)
if(cell[STATUS_VALUE] == FLAGGED)
  flaggedCells.add(cell);
return flaggedCells;
}

Evitar la desinformación: En ocasiones damos nombre ambiguos o que pueden más que informar, desinformar, ya que, da pistas erróneas de lo que en realidad hace una función, variable o clase. En otras oportunidades tenemos variables casi con el mismo nombre donde solo las diferencia una pocas letras o una pequeña palabra, es decir, nombre con variaciones mínimas. Estos casos nos dificultan la lectura del código, razón por la que debemos mejorar en dicho aspecto. Veamos unos ejemplos.

Incorrecto	Correcto	Explicación
tmp	temperatura	Algunos pensaran que tmp, hace referencia a temporal o tiempo
lugarXCoordenadas lugarYCoordenadas	coordenadasOrigen corrdenadasDestino	los nombres tienen forma similar
o	-	Nombrar una variable como o puede hacer que se confunda con el cero, al igual que no brinda ninguna información

Realizar distinciones con sentido: Esta regla va de la mano con la anterior cuando se habla de no tener nombre con variaciones mínimas, debido a que esta regla propone que a dichos nombres se le agregue aparte de una notable variación, sentido, como lo dice el autor “Si los nombres tienen que ser distintos, también deben tener un significado diferente”. Imaginemos que tenemos en una función que recibe dos variables num1, num2, lo primero que notamos es que en sus nombres no tienen una gran diferencia y segundo no da mucha información, ahora, si esta función lo que hace es dividir el primer parámetro (num1) con respecto al segundo (num2), tendría mas sentido llamarlos dividendo y divisor respectivamente.

Usar nombres que se puedan pronunciar: Cuántas veces haciendo mantenimiento al código tienes que dirigirte a un colega para alguna explicación o aclaración, cómo le dirías, o mejor, cómo pronunciarías la variable llamada genymdhms (fecha de generación, año, mes, día, hora, minuto y segundo), ¿no crees que es mejor generationTimestamp? - Ejemplo tomado del libro Clean Code -. Quizás tu colega no te entienda o tenga que ver con sus propios ojos de que le estás hablando, de ahí la importancia de colocar nombres que puedas pronunciar; la programación es una actividad social.

Usar Nombres que se puedan buscar: Aunque es una regla muy lógica, solemos pasar por alto y cuando debemos buscar una variable llamada t, en todo un proyecto o solo en una clase de muchas líneas obtendremos muchos falsos positivos, no sería más fácil buscar una variable llamada TEMPERATURA_MAXIMA_PERMIDA, siendo esta una constante.

Evitar codificaciones: Crear codificaciones para nombre supone una carga extra que debemos aprender y por lo general son difíciles de pronunciar lo que estaría rompiendo la regla de Usar nombres que se puedan pronunciar.

Notación húngara: El autor nos quiere decir que este tipo de notación o codificación en la actualidad no es necesaria y lo que genera son obstáculos que dificultan la lectura del código. Pero, ¿qué es la notación húngara?, es un sistema utilizado para crear los nombres de las variables, este sistema utiliza prefijos para indicar el tipo de dichas variables, por ejemplo, se utiliza el prefijo b para las variables booleanas (bIsCanceled).

Prefijo de miembros: Ya no es necesario utilizar esa práctica que aconsejaba agregar el prefijo m_ a los nombre de variables, los entornos actuales nos permite identificar los miembros ya sea que los resalta o les cambia el color.

Interfaces e implementaciones: Agregar adornos a los nombre de las interfaces (por ejemplo una I inicio del nombre), es agregar más información de lo necesario, y en caso de necesitar implementar dicha interfaz se puede agregar el sufijo Impl, por ejemplo, si tenemos la Interfaz Presenter (note que no la llame IPresenter) su implementación podría llamarse PresenterImpl.

Evitar asignaciones mentales: La asignación mental ocurre cuando el nombre de una variable debe ser traducido mentalmente por quien lee el código para relacionar con algún término del dominio, este problema es habitual con nombres de variables de una sola letra.

Nota: Como el post se está haciendo muy extenso y no quiero cansarte, he decidido tomar aquel consejo de "divide y vencerás". Por tal razón terminaré de contarles acerca del capítulo 2 de Clean Code en el siguiente post (Clean Code Capítulo 2 Nombres con Sentido (2/2)). Para más artículos relacionados ver Clean Code