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:

 

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:

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.

¿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?

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.

¿Te resulta difícil de leer no?

 

Realizar distinciones con sentido

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?

 

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

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

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

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

¿ 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:

Usar nombres que se puedan buscar

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?

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

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?

 

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?

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

 

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

 

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.