SOFTWARE CRAFTMANSHIP - 002

NOMBRES CON SIGNIFICADO 

Los nombres están por doquier en nuestro software. Nombramos nuestras variables, funciones, argumentos, clases y paquetes. Nombramos nuestros archivos fuente, los directorios que los contienen. Nombramos los archivos JAR, WAR e EAR.

Nombres nombres nombres, lo hacemos tanto que deberíamos hacerlo bien desde el principio. A continuación veremos algunas reglas simples para crear buenos nombres.

Use Nombres que REVELEN-INTENCION

El nombre de una variable, función o clase, debería contestar todas las grandes preguntas. Debería decirnos Porque existe, Que hace y Como se usa.

Si un nombre requiere de un comentario para explicarla entonces carece de intención.

int d; // tiempo transcurrido en días

El nombre d no revela nada. No evoca el sentido de tiempo transcurrido o días. Deberíamos escoger un nombre que especifique: Que se está midiendo y su unidad de medida.

int tiempoTranscurridoEnDias;
int diasDesdeCreacion;
int diasDesdeModificacion;
int edadArchivoEnDias;

Escoger nombres que revelan intención pueden hacer más fácil el entender el código. Vea el código a continuación y diga cual es su propósito.

public List<int[]> getTodos() {
  List<int[]> lista1 = new ArrayList<int[]>();
  for (int[] x : laLista)
  if (x[0] == 4)
    lista1.add(x);
  return lista1;
}

Porque es tan difícil decir que esta haciendo este código? No hay expresiones complejas. La indentación y los espacios son razonables. Hay solo tres variables y dos constantes mencionadas. No hay ni siquiera ninguna lujosa clase o método polimorfo, solo una lista de arreglos (o eso parece).

El problema no es la simplicidad del código pero si lo implícito del código: el grado en el cual el contexto no es explicito esta en el código mismo. El código implícitamente requiere que sepamos las respuestas a preguntas como:

1.- Que clase de cosas están en “laLista”?
2.- Cual es el significado del indice cero en los items de "laLista"?
3.- Cual es el significado del valor 4?
4.- Como usare la lista resultante?

Evite la Desinformación

Las respuestas a estas preguntas no están presentes en el código, pero pudieron estar!.  Imaginemos que trabajamos en el juego "Busca Minas".  Descubrimos que el tablero es una lista de celdas llamadas "laLista".  Renombremosla a "tableroDelJuego".

Cada celda en el "tableroDelJuego" esta representada por un arreglo simple.  Mas adelante descubrimos que el indice cero es la ubicación de un valor de estado (status) donde el 4 significa "marcado" (flagged).  Al aplicar estos simples nombres el código mejora considerablemente:

public List<int> getCeldasMarcadas() {
 List<int> celdasMarcadas = new ArrayList<int>();
 for (int[] celda : tableroDelJuego)
 if (celda[VALOR_ESTATUS] == MARCADA)
   celdasMarcadas.add(celda);
 return celdasMarcadas;
}

Note que la simplicidad del código no ha cambiado. Es todavía el mismo numero de operadores y constantes, con exactamente el mismo numero de niveles entrelazados. Pero el código se ha convertido en algo mucho mas explicito.

Podemos ir mas lejos y escribir una clase simple para las celdas en lugar de usar un arreglo de enteros.  Esta puede incluir en su interior una función cuya intención sea revelar su estado (llamemos la "estaMarcada") escondiendo asi los números mágicos.  La nueva versión de la función seria:

public List<Celda> getCeldasMarcadas() {
 List<Celda> celdasMarcadas = new ArrayList<Celda>();
 for (Celda celda : tableroDelJuego)
 if (celda.estaMarcada())
   celdasMarcadas.add(celda);
 return celdasMarcadas;
}

Con estos simples cambios de nombre no es dificil entender que ocurre.