🥇 Nomenclatura descriptiva

Los nombres pueden ser encontrados en cualquier parte del software, en funciones, variables, argumentos, clases, paquetes, archivos de código fuente, los directorios en donde estos se encuentran, etc.

🍿 ¿Cuáles son las recomendaciones para elegir nombres adecuados?

🥤 Incluye intencionalidad como parte del nombre

Los nombres que elijamos deben incluir como parte de ellos alguna intención. Elegir nombres correctos toma tiempo pero ahorra mas del que requiere.

El nombre de una variable, función o clase debe responder preguntas como:

Ejemplos:

int tiempoTranscurridoEnDias
int diasDesdeLaCreacion
int diasDesdeLaModificacion
int antiguedadEnDias

El elegir nombres que revelen intención permite que el código sea mucho mas sencillo de entender y actualizar.

🥤 Evita la desinformación

Los programadores deben evitar dejar pistas falsas que confundan el significado del código. Evita palabras cuyo significado pueda tener diferentes significados.

No cree variables como listaDeCuentas a menos que esta variable en realidad sea una lista List. Una mejor opción sería utilizar un nombre como grupoDeCuentas.

🥤 Realiza una distinción de aquello que tenga mayor significado

Los programadores crean problemas para ellos mismos cuando escriben código con el único propósito de que este sea lo suficientemente bueno para pasar la compilación.

No es suficientes el añadir números o caracteres aleatorios como parte de la nomenclatura, si bien esto generaría nombres únicos no se transmite como parte de ellos un significado.

Las series de números como {a1, a2, a3….aN} es lo opuesto a utilizar nombres con intencionalidad, no son informativos y no proveen pistas sobre la intención del autor.

El ruido en las palabras es otra forma de nomenclatura sin intención, tener simultáneamente nombres como Producto o ProductoInfo o ProductoData fomenta la confusión ya que no se aborda el propósito de cada una de estos nombres.

El ruido también produce redundancia, palabras como “el, los, las” no deben ser utilizadas para nombrar variables como “elCosto” o “laComision”. La palabra variable no debería aparecer nunca como parte del nombre de una variable.

🥤 Utilizar nombres pronunciables

Una parte del cerebro esta dedicada al concepto de las palabras. Las palabras como tales son pronunciables así que hay que asegurarse que los nombres que elijamos se puedan pronunciar.

Si no podemos pronunciar algo no podemos discutir sobre ello, esto se vuelve esencial durante los procesos de mentoría con los nuevos programadores, a los cuales hay que darles una explicación general y dentro de esta poder pronunciar los nombres de variables, clases y métodos, para poder describir su uso.

🥤 Utiliza nombres que se puedan buscar

Cuando usamos nombres que constan de un solo caractér generamos un problema de localización, ya que poder ubicar estos nombres dentro del código se vuelve complicado. Este problema se complica cuando por ejemplo el nombre consta de un número largo combinado o no con otros caracteres.

Los nombres de un solo caractér solo pueden ser utilizados para variables locales dentro de funciones o métodos. La longitud de la variable debe estar en concordancia con la de su scope. Si esta variable será utilizada dentro de diferentes scopes entonces se debe utilizar un nombre descriptivo que sea ademas fácil de localizar.

🥤 Evita los nombres codificados

El codificar los nombres solo agrega mas trabajo al momento de intentar descifrar la intención. Esto requiere un trabajo mental adicional innecesario cuando se desea resolver un problema. Los nombres codificados son difíciles de pronunciar y fácilmente de escribir incorrectamente.

🥤 No utilices la notación húngara (hungarian notation)

La notación húngara tuvo como finalidad resolver ciertos problemas en la programación en el pasado, cuando cada elemento creado en la programación tenia asociado un entero como referencia o un puntero

En lenguajes modernos tenemos mejores y mas organizadas formas de tipado de las que se tuvieron en el pasado. Existe ademas una tendencia de hacer las clases y funciones mas pequeñas de forma que se pueda ver de forma sencilla el punto en el que por ejemplo las variables han sido declaradas.

La notación húngara y otro tipo de formas de codificación son simplemente impedimentos. Hacen mas difícil cambiar el nombre o el tipo de una variable, función o clase. Hacen también mas difícil de leer el código y crean la posibilidad de que se engañe al lector.

🥤 No utilices prefijos

En el pasado se solían utilizar prefijos como m_ para distinguir en lenguajes como java una variable local de una propiedad de una clase. Esto ya no es necesario debido a que los editores pueden mostrar mediante coloreado la distinción entre un tipo y otro. Si se desea mas claridad prime el uso de this.nombreDeLaPropiedad para marcar una diferencia con las variables locales.

🥤 Utilice nombres codificados solo en la implementación de las interfaces

Evite crear nombres como IFigura para hacer referencia a una interfaz, en su lugar mantenga un nombre sin prefijos y codifique la implementación. Por ejemplo Figura sería el nombre de su interface mientras que Rombo sería el nombre de la implementación.

🥤 Evite el uso de mapas mentales

Quienes leen el código no deberían de tener que traducir nombres en otros nombres. Este problema se presenta en especial con nombres de un solo caractér en situaciones como loops. Es esperable que un loop contenga nombres como i y j si el scope de estas variables es pequeño y no hay otros nombres de variables que se entren en conflicto. En otro tipo de contextos utilizar una sola letra no es considerado un buen habito, es decir que crear una variable llamada c, que porque a y b ya han sido definidas es una mala práctica.

Una cosa que diferencia a un programador inteligente de aquel que no lo es, es su capacidad de entender que la claridad prima a la hora de programar. Los programadores profesionales entienden que deben escribir código que se sencillo de entender.

🥤 ¿Cuál es la forma correcta de nombrar clases en programación?

Las clases deben ser sustantivos o frases de sustantivos como Cliente, Cuenta, Direccion o AnalizadorDeDireccion. Hay que evitar utilizar nombres de clases como Administrador, Procesador, Datos o Info. Ademas de lo anterior considerar que una clase no debe ser un verbo, es decir no podemos usar clases como ProcesarOrden.

🥤 ¿Cuál es la forma correcta de nombrar métodos en programación?

Los métodos deben tener un verbo como parte de su nombre, ejemplos de esto son borrarPedido, procesarPago o simplemente guardar. Los accesors, mutators y predicates deben ser nombrados utilizando el valor que accesan o mutan precedido del prefijo set, get o is. Ejemplos de esto son getTotal(), setTotal(val), isPagado().

Cuando los constructores son sobrecargados, utilice métodos estáticos con nombres que describan los argumentos.

Complex fulcrumPunto = Complex.FromRealNumber(23.0);

Para el caso anterior considere hacer el constructor privado, de forma que new Complex() no pueda ser utilizado.

🥤 Evite el uso de slangs

No todos tienen el mismo sentido del humor y no todos son capaces de entenderlo. Elija la claridad sobre cualquier tipo de valor que provenga del entretenimiento. Use nombres de métodos que representen lo que el método quiere realizar y evite frases populares que solo aporten humor y confusión.

🥤 Elija una palabra por concepto

Es confuso que en un proyecto se usen de forma simultanea palabras como leer, extraer y retraer cuando hacen todas ellas el mismo tipo de actividad. También puede ser confuso tener un controlador y administrador de manera simultanea dentro del proyecto, ambos realizando la misma actividad.

🥤 Evite usar la misma palabra para múltiples propósitos

Siga la regla de una palabra por concepto, esto puede provocar que termine con muchas clases que tengan un método agregar. Mientras la lista de parámetros y el tipo de valor retornado de los diferentes métodos sea semánticamente equivalente, esto esta bien.

Sin embargo alguien puede decidir utilizar la palabra agregar para términos de consistencia cuando en realidad no se esta utilizando en el mismo sentido, si por ejemplo usamos métodos agregar para ir incrementando los productos asociados a una compra, pero simultáneamente deseamos poder crear un registro único para dicho pedido, podemos para tal caso usar agregar e insertar para cada uno de los casos.

Nuestro objetivo es hacer que el código sea tan sencillo de entender como sea posible. Que el autor tenga la responsabilidad de que lo que escribe sea interpretado por quien lee, y no sea necesario un interprete para poder hacerlo.

🥤 Use soluciones del dominio

Las personas que leen el código serán programadores. Así que esta bien utilizar términos de programación provenientes del área de la Ciencia de la Computación, como pueden ser nombres de algoritmos, de patrones, términos matemáticos, etc. Usar nombres como NotificacionFila es un nombre que indica un sustantivo y al mismo tiempo un término informático. Esto desde el punto de vista del código limpio esta bien.

Separar los conceptos de la solución y el problema es parte del trabajo de un buen programador. Cuando el código tenga mas relación con soluciones deberá utilizar términos asociados a estas soluciones, si por el contrario se enfoca en los problemas, los términos serán relacionados con el problema abordado.

🥤 Utiliza nombres de problemas del dominio

Cuando no hay opciones claras para nombrar, utiliza la posibilidad de dar nombres relacionados con el problema del dominio. Separar los conceptos de solución del problema es parte del trabajo de un buen programador.

🥤 Agrega contenido con significado

Para elegir nombres con significado busque nombres que tengan contexto para el lector encerrandolos en clases bien nombradas, funciones o namespaces. Si todo lo anterior falla utilice prefijos, pero siempre como último recurso.

Si hay datos como nombre, apellido, estado, etc. y estos forman parte de un formulario de dirección, podemos agregar un prefijo para hacer notar que todas estas forman parte del mismo contexto utilizando nombres como addrName, addrLastName, addrState, de esta forma el lector entenderá que estas variables forman parte de una contexto mayor.

🥤 No agregue contexto solo por agregar

Es una mala práctica agregar contexto a las variables solo por la necesidad de agregarlo. Si se tuviese por ejemplo una aplicación llamada Generador de Etiquetas seria una mala idea que todas las variables llevaran un prefijo gde.

Los nombres accountAddress y customerAddress son adecuados para instancias de la clase Address, pero si dentro del código existen otro tipo de direcciones como mac address, y port address sería una mejor idea buscar nombres mas significativos como PostalAddress, Mac y Url.

¿Qué es el código limpio? Funciones
comments powered by Disqus