9 Pautas para Crear Nombres Expresivos

27 de octubre de 2019 • 6 min de lectura

Nombrar es subjetivo y situacional, es un arte, y como con la mayoría del arte, descubrimos patrones. He aprendido mucho leyendo el código de otros. En este artículo, he compilado 9 pautas que desearía que otros hubieran seguido cuando leí su código.

Cuando un ingeniero de software abre una clase, debería saber, basándose en los nombres, las responsabilidades de la clase. Sí, sé que nombrar es solo un radio de la rueda, las estructuras físicas y lógicas también juegan un papel significativo en la comprensión del código, así como la complejidad. En este artículo, me estoy enfocando únicamente en nombrar porque siento que es el impacto más significativo en la comprensión del código.

No Incluyas el Tipo a Menos que Clarifique la Intención

Un tipo puede ser cualquier cosa desde un tipo de programación (string, int, decimal) hasta una agrupación de responsabilidades (Util, Helper, Validator, Event, etc.). A menudo es una clasificación que no expresa intención.

Veamos un ejemplo: El nombre StringHelper no expresa mucho. Un string es un tipo del sistema, y Helper es vago, StringHelper habla más del “cómo” que de la intención. Si en su lugar, cambiamos el nombre a DisplayNameFormatter se nos da una imagen más clara de la intención. DisplayName es muy específico, y Formatter expresa resultado. Formatter puede o no ser un tipo, pero no importa, porque expresa intención.

Siempre hay excepciones; por ejemplo, en ASP.Net MVC, los controladores deben terminar en “Controller” o la aplicación no funciona. Usando paradigmas como Domain Driven Design (DDD), nombres como “Services,” “Repository,” “ValueType” y “Model” tienen significado en DDD y expresan responsabilidad.

Por ejemplo, UserRespository implica que los datos del usuario se recuperan y guardan en un almacén de datos.

Evita las Metáforas

Las metáforas son culturales, y los ingenieros de otras culturas podrían no entender la intención.

Metáforas comunes en los Estados Unidos:

• Beating a dead horse
• Chicken or the egg
• Elephant in the room

Metáforas comunes en Nueva Zelanda:

• Spit the dummy
• Knackered
• Hard yakka

Usa Verbos

Steve Yegge escribió una (muy larga) publicación de blog sobre usar verbos en lugar de sustantivos.

Su punto es usar verbos, las aplicaciones están compuestas de sustantivos, pero los sustantivos no hacen cosas. Los sistemas son inútiles con solo sustantivos, en su lugar expresa acción en los nombres de los métodos.

Por ejemplo, UserAuthentication*(sustantivo).AuthenticateUser(acción/verbo)* expresa la acción de verificar las credenciales de un usuario.

Sé Descriptivo

Sé descriptivo, mientras más detalle, mejor — expresa la responsabilidad en el nombre.

Pregúntate, ¿cuál es la única cosa que esta clase o función hace bien?

Si tienes dificultad encontrando un nombre, la clase o función podría tener más de una responsabilidad y así violar el Principio de Responsabilidad Única.

No Te Apoyes en Comentarios para la Intención

Los comentarios son una gran manera de proporcionar contexto adicional al código pero no te apoyes en comentarios. Los nombres de clases y métodos deberían sostenerse por sí solos.

En Refactoring: Improving the Design of Existing Code por Martin Fowler, Kent Beck, John Brant, William Opdyke, y Don Roberts:

… los comentarios a menudo se usan como desodorante. Es sorprendente qué tan a menudo miras código densamente comentado y notas que los comentarios están ahí porque el código es malo.

Otra cita maravillosa de los autores de “In Refactoring”:

Cuando sientes la necesidad de escribir un comentario, primero trata de refactorizar el código para que cualquier comentario se vuelva superfluo. Página 88

Muchas veces cuando el código es refactorizado y encapsulado en un método, encontrarás otras ubicaciones donde es posible aprovechar el nuevo método, lugares que nunca anticipaste usar el nuevo método.

A veces cuando se llama a un método el consumidor necesita saber algo particular sobre el método, si esa particularidad es parte del nombre, entonces el consumidor no necesita revisar el código fuente.

Aquí hay un ejemplo de incorporar un comentario en un nombre.

Con comentarios:

// without tracking
var user = GetUserByUserId(userId);

Refactorizado para incluir el comentario en el nombre del método:

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

Otros ingenieros ahora saben que este método no tiene seguimiento antes de que necesiten leer el código fuente o encontrar el comentario.

Los comentarios deberían ser tu última línea de defensa cuando sea posible apóyate en otras formas de expresar intención incluyendo usar estructura física y lógica y nombres para transmitir intención.

Abstente de Usar Nombres con Significado Ambiguo

Evita nombres con significados ambiguos. El significado de nombres ambiguos cambia de proyecto a proyecto lo que hace que entender la intención sea más difícil para un nuevo ingeniero.

Aquí hay una lista de nombres ambiguos comunes:

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

Usa el Mismo Lenguaje que el Dominio del Negocio

Usa la misma terminología en el código que en el dominio del negocio. Esto permite a los ingenieros y expertos en la materia (SME) comunicar ideas fácilmente porque comparten el mismo vocabulario. Cuando no hay un vocabulario compartido ocurre traducción lo que invariablemente lleva a malentendidos.

En un proyecto en el que trabajé, el negocio comenzó con “Pupil” y luego cambió a “Student.” Los ingenieros de software nunca actualizaron el software para reflejar el cambio en terminología. Cuando nuevos ingenieros se unieron al proyecto la mayoría creía que Pupil y Student eran conceptos diferentes.

Usa Jerga de la Industria

Cuando sea posible, usa terminología que tenga significado a través de la industria del software.

La mayoría de los ingenieros de software, cuando ven algo llamado “factory,” inmediatamente piensan en el patrón factory.

Usar paradigmas de aplicación existentes como “Clean Architecture” y “Domain Driven Design” facilita el intercambio de ideas y crea un lenguaje común para que los ingenieros comuniquen ideas entre ellos.

La peor nomenclatura posible es cooptar terminología de toda la industria y darle un significado diferente.

Al Nombrar Booleanos…

Los nombres booleanos siempre deberían ser una respuesta a una pregunta con su valor de verdadero o falso.

Por ejemplo, isUserAutheticated, la respuesta es ya sea sí (true) o no (false)

Usa palabras como:

• Has
• Does
• Is
• Can

Evita nombres negados, por ejemplo:

Un nombre de variable negado:

var IsNotDeleted = true; // esto es confuso

if(!IsNotDeleted) { // se vuelve aún más confuso cuando el valor es negado
  //Do magic
}

Sin nombre de variable negado:

var IsDeleted = true; // esto es confuso

if(!IsDeleted) { 
  //Do magic
}

En Conclusión

Elegir nombres expresivos es crucial para comunicar intención, diseño y conocimiento del dominio al siguiente ingeniero. A menudo trabajamos en código para corregir defectos o incorporar nuevas características, y continuamente estamos compilando código en nuestra cabeza tratando de entender cómo funciona. Nombrar nos da pistas sobre lo que el ingeniero anterior estaba pensando, sin esta comunicación entre los ingenieros del pasado y del futuro nos limitamos en el crecimiento de la aplicación. Potencialmente condenando el proyecto al fracaso.