Clean Code Capítulo 2 Nombres con Sentido (2/2)

Continuando con la segunda parte del capítulo 2, vamos a seguir viendo aquellas reglas para crear nombres correctos. Si aún no has visto la primera parte te invito para que la veas.

Nombres de clases: Los nombre de clases no deben ser verbos. Los nombres deben proporcionar de manera clara el propósito de la clase, por lo general debe ser un sustantivo, evitando nombres genéricos. Algunos ejemplos de nombres correctos serían: Persona, Direccion, Cliente. Algunos nombres incorrectos de clases podrían ser: Info, Procesador, CalcularNomina.

Nombre de métodos: Debe ser un verbo como por ejemplo, eliminar, agregar, guardar. Los métodos de acceso, modificación deben tener como nombre su valor y usar como prefijo get, set e is. Como recomendación el autor dice, que “Al sobrecargar constructores use métodos de factoría estáticos con nombres que describan los argumentos”

No se exceda con el atractivo: Esta regla hace referencia a no utilizar nombres provenientes de formas coloquiales de decir las cosas o de jergas, dejando a un lado la claridad, ya que, si llega un nuevo programador que no conozca estas formas de decir las cosas, se llenará de desinformación. 

Un nombre por concepto: Es simple, cuando nos decidimos por una palabra para representar un concepto, esta debe ser constante por todo el código y no utilizarse en unos lados y en otros no. Por ejemplo, no es conveniente utilizar en algunos nombres de métodos la palabra get y en otros retrieve. 

No haga juego de palabras: Se refiere a no utilizar una palabra con dos fines distintos, por ejemplo, digamos que en nuestro código hemos venido utilizando la palabra remove para nombrar métodos que inactivan, y en algún momento somos tentados a utilizar remove para hacer referencia a un método que elimina, en este caso sería mejor utilizar el nombre delete para el método en cuestión.

Usar nombres de dominio de soluciones: No es necesario que todos los nombres utilizados sean extraídos del dominio del problema, ya que, los lectores del código son programadores y ellos conocen o están familiarizados con términos informáticos, de patrones, y demás. Por ejemplo para un programador va a tener mucho sentido si una clase tiene el nombre de ListAdapter.

Usar nombre de dominios de problema: Cuando no se pueda cumplir la regla anterior porque no existe un término en el ámbito de programación, se debe recurrir a un nombre del dominio del problema. El autor nos dice “Separar los conceptos de dominio de soluciones y de problemas es parte del trabajo de un buen programador y diseñador”.

Añadir contexto con sentido: Cuando los nombres no tiene sentido por sí mismo, es necesario crearle un contexto que enriquezca dicho nombre, esto puede hacerse convirtiendo variables en parte de un concepto mayor, es decir, extraer una clase de la cual hagan parte o en una función o método que aporte un contexto. Como última instancia usar prefijos.

No añadir contextos innecesarios: Se refiere a no agregar en los nombres más información de la necesaria. Imagine una clase llamada DireccionResidencia y otra DireccionTrabajo, estos nombres no son realmente adecuados para una clase, lo mejor sería una clase Direccion y estos nombres serían ideales para nombre de instancias. Otro caso es agregar prefijo al nombre de las clases.

Como hemos visto en estos dos post acerca de nombres con sentido, el elegir un nombre adecuado para cada parte del código es fundamental, tanto para la legibilidad como para entender qué se hizo o qué se va a hacer. Para dar un nombre adecuado es necesario emplear habilidad descriptiva, gran vocabulario, conocimiento técnico y dejar los miedos, es momento de empezar a buscar mejores nombres, agregar o quitar el exceso de contexto, refactorizar el código, cambiando los nombres que no sean adecuados en el código existente.

Nota: Para más artículos relacionados ver Clean Code

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