Cómo ser grandioso al dar nombres significativos

¿Por qué nombres significativos?

  • Considera que estás nombrando a un niño (¿suena demasiado fácil, verdad?)
youAreMyKid (), cuteLittleBaby (), shyBaby ()
  • Supongo que querrías considerar esos nombres.
Solo hay dos cosas difíciles en informática: invalidación de caché y nombrar cosas - Phil Karlton

Tendemos a formar identidades, almacenar y recuperar información relacionada sobre lugares, cosas de personas en función de sus nombres. Del mismo modo, los nombres están en todas partes, incluso en el código más pequeño que escribimos. Nombramos nuestras variables, funciones, argumentos, clases y paquetes.

Nombramos nuestros archivos fuente y los directorios que los contienen. Si los nombres no revelan las intenciones correctas, no son distintos y no son fáciles de recordar, la legibilidad del código disminuye drásticamente. En este artículo, intentaré compartir mis aprendizajes de Clean Code de Robert C Martin. Lo que sigue son algunas convenciones realmente buenas para dar nombres propios en nuestro código para evitar situaciones confusas como ¿quién fue John The Third y quién fue John The Third Junior?

Una diferencia entre un programador inteligente y un programador profesional es que el profesional entiende que la claridad es la reina. Los profesionales usan sus poderes para bien y escriben código que otros pueden entender - Robert C. Martin

Utilice nombres reveladores de intenciones

El nombre de una variable, función o clase debe responder a todas las grandes preguntas. Debería decirle por qué existe, qué hace y cómo se usa. Si un nombre requiere un comentario, entonces el nombre no revela su intención.

Malo

int d; // tiempo transcurrido en días
// El nombre d no revela nada

Limpiar

int elapsedTimeInDays;

¿Puedes decir cuál es el propósito del siguiente código? Piensa por un minuto

def get_them ()
 lista1 = []
 the_list.each do | tl |
   si tl [0] == 4
    list1.push (tl)
   fin
 fin
 lista de retorno1
fin

Preguntas:

1. ¿Qué tipo de cosas hay en la lista?
2. ¿Cuál es el significado del subíndice cero de un elemento en la_lista?
3. ¿Cuál es el significado del valor 4?
4. ¿Cómo usaría la lista que se devuelve?

Las respuestas a estas preguntas no están presentes en el ejemplo de código, pero podrían haber estado.

Evitar la desinformación

Los programadores deben evitar dejar pistas falsas que oscurezcan el significado del código. El uso de ortografías inconsistentes es desinformación. No refiera la lista de la factura de ventas a la lista de facturas de ventas. en su lugar, use el grupo de facturas de ventas, facturas de ventas o grupos de facturas de ventas

Una forma más de desinformación en los nombres sería el uso de mayúsculas y minúsculas en combinación. Si sigues camelCase, ve a la convención camelCase. pero no mezcle y combine, es decir, SalesInVoice, SavingAccOunt, etc.

Hacer distinciones significativas

No debe usar el mismo nombre para referirse a dos cosas diferentes en el mismo ámbito. Es posible que sienta la tentación de cambiar un nombre de forma arbitraria.

Las palabras ruidosas son una distinción sin sentido. Por ejemplo, imagine que tiene una clase de Producto. Si ha hecho una clase más con un ProductInfo o ProductData llamado, ha hecho que los nombres sean diferentes sin hacer que signifiquen algo diferente. Información y datos son palabras de ruido indistintas como a, an y the.

Distinga los nombres de tal manera que el lector sepa lo que ofrecen las diferencias. moneyAmount no se puede distinguir del dinero, customerInfo no se puede distinguir del cliente, accountData no se puede distinguir de la cuenta

Usar nombres pronunciables

Los nombres fácilmente pronunciables son fácilmente recuperables. Si no puede pronunciarlo, no puede discutirlo sin sonar como un idiota

Comparar

clase DtaRcrd102 {
   fecha privada genymdhms;
   Fecha privada modymdhms;
   Cadena privada final pszqint = ”102”;
   / * ... * /
};

a

clase Cliente {
   Fecha privada Generación Fecha y hora;
   Modificación de fecha privada Marca de tiempo;
   Private final String recordId = ”102”;
};

Usar nombres buscables

La búsqueda de variables por nombre en una gran base de código es algo frecuente para los programadores mientras depuran o intentan rastrear dónde se está utilizando toda esa variable, clase o función. Los nombres de una letra y las constantes numéricas tienen un problema particular, ya que no son fáciles de ubicar en un cuerpo de texto. Evita usarlos.

Evitar codificaciones

Codificar información de tipo o alcance en nombres simplemente agrega una carga adicional de descifrarlo y agrega fricción cognitiva al recordarlo. No parece razonable exigir que cada nuevo empleado aprenda otro lenguaje de codificación además de aprender el (generalmente considerable) cuerpo de código en el que trabajarán.

Evite codificaciones innecesarias de tipos de datos junto con el nombre de la variable.

String firstNameString; Flotador peso Flotador;

Es posible que no sea necesario cuando el mundo entero sabe muy bien que, en un contexto de usuario, el primer nombre tendrá una secuencia de caracteres. Lo mismo ocurre con Peso, que es decimal / flotante.

Evitar mapeo mental

Las colaboraciones ocurren con bastante frecuencia cuando los diferentes equipos están creando módulos separados del mismo producto. Cuando alguien nuevo o de otro equipo está leyendo, no debería tener que traducir mentalmente sus nombres a otros nombres que ya conocen. Este es un problema con los nombres de variables de una letra. Ciertamente, un contador de bucle puede llamarse i o j o k (¡aunque nunca l!) Si su alcance es muy pequeño y ningún otro nombre puede entrar en conflicto con él. Esto se debe a que los nombres de una letra para los contadores de bucles son tradicionales.

Malo

ubicaciones = ["Austin", "Nueva York", "San Francisco"]
ubicaciones.e cada do | l |
 hacer cosas
 #do_some_other_stuff
 # otras cosas
 # Espera, ¿para qué sirve 'l'?
 despacho (l)
fin

Limpiar

ubicaciones = ["Austin", "Nueva York", "San Francisco"]
ubicaciones.e cada do | ubicación |
 #hacer cosas
 #do_some_other_stuff
 # ..
 despacho (ubicación)
fin

Nombres de clase

Las clases y los objetos deben tener nombres con nombres o frases nominales como Cliente, WikiPage, Cuenta y AddressParser. Evite palabras como Administrador, Procesador, Datos o Información en el nombre de una clase. Un nombre de clase no debe ser un verbo.

Nombres de métodos

Los métodos deben tener nombres de verbos o frases verbales como postInvoice, deleteShipment

Elija una palabra por concepto

Elija una palabra para un concepto abstracto y manténgalo. Por ejemplo, es confuso tener que buscar, recuperar y obtener como métodos equivalentes de diferentes clases. ¿Cómo recuerdas qué nombre de método va con qué clase? Los nombres de las funciones deben estar solos y deben ser consistentes para que pueda elegir el método correcto sin ninguna exploración adicional.

Malo

Información de usuario
datos del usuario
user_record
empieza a
Empieza en
hora de inicio

Limpiar

usuario
Empieza en

otro ejemplo

dataFetcher () vs dataGetter () vs dataRetrieval ()

Si los tres métodos hacen lo mismo, no mezcle ni combine la base del código. En cambio, quédate con uno.

Usar nombres de dominio de solución

Recuerde que las personas que leen su código serán programadores. Así que adelante y use términos de informática (CS), nombres de algoritmos, nombres de patrones, términos matemáticos, etc.

No es aconsejable extraer todos los nombres del dominio del problema porque no queremos que nuestros compañeros de trabajo tengan que correr de un lado a otro al cliente preguntando qué significa cada nombre cuando ya conocen el concepto con un nombre diferente.

El nombre AccountVisitor significa mucho para un programador que esté familiarizado con el patrón VISITOR.

Usar nombres de dominio problemáticos

Cuando no haya "programador-eese" para lo que está haciendo, use el nombre del dominio del problema. Al menos el programador que mantiene su código puede preguntarle a un experto en dominio qué significa.

Si domina eliminar la duplicación y corregir los malos nombres, entonces afirmo que domina el diseño orientado a objetos - J. B. Rainsberger extraído de Los cuatro elementos del diseño simple

Añadir contexto significativo

Hay algunos nombres que son significativos en sí mismos, la mayoría no lo son. Imagine que tiene variables llamadas nombre, apellido, calle, número de casa, ciudad, estado y código postal. En conjunto, está bastante claro que forman una dirección. Pero, ¿qué pasa si acabas de ver que la variable de estado se usa sola en un método

Puede agregar contexto mediante el uso de prefijos: addrFirstName, addrLastName, addrState, etc. Por supuesto, una mejor solución es crear una clase llamada Address

Escribir código limpio es un arte y requiere práctica, mucho.

Conclusión

Lo más difícil de elegir buenos nombres es que requiere buenas habilidades descriptivas y un trasfondo cultural compartido. Este es un problema de enseñanza en lugar de un problema técnico, comercial o de gestión. Nadie es bueno para nombrar, especialmente cuando te apresuras a cumplir el plazo.

La gente también teme renombrar las cosas por temor a que otros desarrolladores se opongan. No compartimos ese miedo y descubrimos que estamos realmente agradecidos cuando los nombres cambian (para mejor)

Por lo tanto, configure su convención de nomenclatura pronto si aún no está en su lugar y deje el código limpio. ¡Feliz codificación!