Nombres con Sentido

En el software los nombres son omnipresentes, los usamos constantemente, por ello debemos hacerlo correctamente.

Reglas básicas para crear nombres correctos

Usar nombres que revelen las intenciones

Elegir el nombre correcto lleva tiempo pero también ahorra trabajo. Cámbielos cuando encuentre otro mejor.

El nombre de una variable, función o clase debe responder una serie de cuestiones básicas:

¿Por qué existe? ¿Que hace? ¿Como se usa?

Si un nombre requiere un comentario, significa que no revela su cometido.

Ejemplo:

int d; // Numero de días de vida

int diasDeVida;

 

La elección de nombres que revelen intenciones facilita considerablemente la comprensión y la modificación del código.

Evitar la desinformación

Se debe evitar dejar pistas falsas que dificulten el significado del código. Se debe evitar palabras cuyo significado se aleje del que pretendemos.

Ejemplo:

int hp;

hp se refiere a hipotenusa. Aunque parezca la abreviatura correcta para algunos, puede no serlo para otros.

 

El nombre no debe hacer referencia al tipo de dato que devuelve si no aporta informacion.

string nombreString;

¿Puede ser un nombre otra tipo sin ser String? Si es que no, es desinformación.

¿Si en un futuro en vez de devolver un string devolviéramos un char?¿Cambiaremos el nombre nuevamente?

 

Evitar usar nombres con variaciones mínimas, ¿cuanto tardas en averiguar la diferencia entre estas variables?

int numeroDeVueltasRealPorMinuto;
int numeroDeVueltasEsperadasPorMinuto;

Ambas palabras tienen una forma similar.  Intentar buscar alternativas en estos casos.

 

Otro caso de desinformación seria el uso de la l minúscula o la O mayúscula como nombres de variables.

int l = 1;
int O = 0;
if( O == 1){
  a = 0;
} else {
  l = 1;
}

¿Te resulta difícil de leer no?

 

Realizar distinciones con sentido

function copiar(a1,a2){
  a1 = a2;
}

El compilador no nos falla con estas variables ya que son distintas.

a1 y a2 no desinforman, simplemente no dan información.

¿No crees que se lee mejor así la misma función?

function copiar(destino,datoACopiar){
  destino = datoACopiar;
}

 

No es incorrecto el uso de palabras adicionales mientras tenga sentido. El problema viene cuando, por ejemplo, tenemos dos variables así:

string casa;
string lacasa;

¿Intuimos que diferencia puede haber con esos nombres? ¿No verdad?

En ausencia de convenciones concretas, no sabríamos las diferencias de por ejemplo:

int dinero;
int cantidadDeDinero;

string usuario;
string infoUsuario;

string elMensaje;
string mensaje;

Se debe diferenciar los nombres de las variables, de forma que, el lector, aprecie las diferencias de forma automática.

Usar nombres que se puedan pronunciar

string nopapsap;//nombre,primer apellido, segundo apellido

¿ Lo podrías pronunciar?  ¿Como le dirías a un compañero que la variable nopapsap le pasa algo?

¿No sería mas fácil asignarle un nombre pronunciable y que sea entendible en nuestro idioma?

Sería mejor renombrarlo a algo como:

string nombreYApellidos;

Usar nombres que se puedan buscar

for(int i=0; i<5; i++){
  ...
}

El numero 5 como tal, seria muy difícil a la hora de buscar en el código o saber su significado.  ¿Por qué no darle un nombre y darle mas semántica al código?

const int NUMERO_DIAS_TRABAJADOS = 5; 
for(int i=0; i<NUMERO_DIAS_TRABAJADOS; i++){
  ...
}

Evitar codificaciones

Ya se usan bastantes codificaciones como para tener que aprender otras internas de la nuevas de la organización. Los nombres codificados resultan impronunciables y suelen escribirse de forma incorrecta.

 

Notación húngara

Hay que evitar su uso ya que dificultan la legibilidad del código y puede ser que el sistema de codificación confunda al lector.

**Notación Húngara: Consiste en hacer que el nombre de una variable empiece con una o más letras minúsculas que indiquen el tipo de dato de la variable.

c – char
by – BYTE (unsigned char)
n – short
i – int

…

 

Evitar asignaciones mentales

let nombres = ["pepe", "juan","santiago"];
let apellidos = ["perez","rodriguez","santana"];

for(i=0; i<nombres.length; i++){
  string j = nombres[i];
  for(x=0; x<apellidos.length; x++){
    string z = apellidos[x];
    console.log(x,z);
  }
}

Viendo este sencillo código, tendremos que buscar y asignar mentalmente el x y z que imprimimos por consola al final, que es el nombre y apellido. ¿Por qué no darles nombres son sentido y evitar la asignación mental?

let nombres = ["pepe", "juan","santiago"];
let apellidos = ["perez","rodriguez","santana"];

let numeroTotalNombres = nombres.length;
let numeroTotalApellidos = apellidos.length;

for(i=0; i<numeroTotalNombres; i++){
  string nombre = nombres[i];
  for(x=0; x<numeroTotalApellidos; x++){
    string apellido = apellidos[x];
    console.log(nombre,apellido);
  }
}

 

Nombres de clases

Deben ser sustantivos.

Nombres de métodos

Deben ser verbos.

Una palabra por concepto

Elija una palabra para concepto abstracto y manténgala en todo el código.

Por ejemplo no usar add en una clase y set en la misma u otra clase para referirse al mismo concepto de añadir/establecer.

 

Añadir contexto con sentido

¿Viendo el siguiente código sabrías decir la dirección a quien pertenece?

let nombrePersona;
let apellidoPersona;
let nombreEmpresa;
let direccion;

Pueden añadirse prefijos o sufijos para añadirle contexto dejándolo en :

let direccionEmpresa;

 

Es mejor crear las clases y se quedaría más claro:

function Persona(nombre,apellido){
  ...
}

function Empresa(nombre,direccion){
  ...
}
let ruteco = new Empresa("ruteco s.a.","c/violeta n90");
console.log(ruteco.direccion);

 

El código debe terminar leyéndose como un libro de instrucciones sin acertijos, que sea entendible por alguien que no ha visto el código anteriormente.