9 Directrices para Crear Nombres Expresivos

La nomenclatura es subjetiva y situacional, es un arte, y como la mayoría de las artes, descubrimos patrones. He aprendido mucho leyendo el código de otros. En este artículo, he compilado 9 directrices 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 la nomenclatura es solo una parte de la rueda, las estructuras físicas y lógicas también juegan un papel significativo en la comprensión del código, al igual que la complejidad. En este artículo, me estoy enfocando solo en la nomenclatura porque creo que tiene el impacto más significativo en la comprensión del código.

No Incluyas Tipo a Menos que Aclare 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 de sistema, y Helper es vago, StringHelper habla más sobre el “cómo” que sobre la intención. Si en cambio, cambiamos el nombre a DisplayNameFormatter nos damos 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, UserRepository implica que los datos del usuario se recuperan y se guardan en un almacén de datos.

Evita Metáforas

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

Metáforas comunes en 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) entrada de blog sobre el uso de verbos sobre sustantivos.

Su punto es usar verbos, las aplicaciones se componen 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, cuanto 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 para encontrar un nombre, la clase o función podría tener más de una responsabilidad y por lo tanto violaría el Principio de Responsabilidad Única.

No Dependas de Comentarios para la Intención

Los comentarios son una excelente manera de proporcionar contexto adicional al código, pero no dependas de comentarios. Los nombres de clases y métodos deben valerse por sí solos.

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

… los comentarios a menudo se usan como desodorante. Es sorprendente con qué frecuencia 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 “Refactoring”:

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

Muchas veces cuando el código se refactoriza y se encapsula en un método, encontrarás otros lugares 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 necesitaran leer el código fuente o encontrar el comentario.

Los comentarios deben ser tu última línea de defensa cuando sea posible, inclínate hacia otras formas de expresar intención, incluyendo el uso de 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 los nombres ambiguos cambia de proyecto a proyecto, lo que hace que la comprensión de 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 que los ingenieros y expertos en la materia (SME) se comuniquen fácilmente porque comparten el mismo vocabulario. Cuando no hay un vocabulario compartido, la traducción ocurre, lo que invariablemente conduce 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 la terminología. Cuando se unieron nuevos ingenieros al proyecto, la mayoría creía que Pupil y Student eran conceptos diferentes.

Usa Terminología de la Industria

Cuando sea posible, usa terminología que tenga significado en toda la industria del software.

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

El uso de 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 se comuniquen entre sí.

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

Cuando Nombres Booleanos…

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

Por ejemplo, isUserAuthenticated, la respuesta es 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 se niega
  //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 compilamos código en nuestras cabezas tratando de entender cómo funciona. La nomenclatura 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 a nosotros mismos en el crecimiento de la aplicación. Potencialmente condenando el proyecto al fracaso.