Hola Habr! Les presento la traducción del artículo "Los nombres largos son largos" de Bob Nystrom.
Una de las cosas inteligentes que hace Google es la estricta revisión del código. Cada cambio, antes de que se le permita llegar a la rama principal, se considera en al menos dos direcciones. Primero, alguien en el equipo realiza una verificación de rutina para asegurarse de que el código haga lo que debería.
Pero luego se produce el segundo paso, cuando se verifica la legibilidad del código. Esto garantiza que otros desarrolladores podrán admitir este código en el futuro. ¿Es este código fácil de entender y mantener? ¿Este código coincide con el estilo y las expresiones idiomáticas del idioma? ¿Está bien documentado el código?
El uso del lenguaje Dart en Google está ganando impulso gradualmente, y me ocupé mucho de dicha revisión de código. Para un desarrollador de idiomas, este es un proceso muy emocionante. Tengo una visión de primera mano de cómo las personas usan Dart, lo cual es realmente útil para su desarrollo. Tengo una idea más clara de qué errores son comunes y qué funciones se usan mucho. Me siento como un etnógrafo, un diario sobre la vida de los nativos.
Pero, en cualquier caso, este no es el caso. Maldita sea, ni siquiera es Dardos. De lo que quiero hablar es de lo que veo en muchos códigos, y lo que me vuelve loco: nombres demasiado largos .
Sí, los nombres pueden ser demasiado cortos. En aquellos días cuando C exigía que solo los identificadores externos fueran únicos hasta los primeros seis caracteres; cuando el autocompletado aún no se ha inventado; cuando cada pulsación de tecla era como subir cuesta arriba por la nieve, esto era un problema. Me alegra que ahora vivamos en una utopía futurista donde los pedos de teclado como p , idxcrpm y x3 son raros.
Pero el péndulo se balanceó demasiado en la otra dirección. No tenemos que ser Hemingway, tampoco necesitamos ser Tennessee Williams. Los nombres demasiado largos también perjudican la claridad del código en el que se usan. Los nombres de variables muy largos eclipsan las operaciones que realiza en ellos. El código se vuelve difícil de escanear visualmente. Para cumplir con los requisitos de ancho de código, aparecen saltos de línea adicionales que interrumpen el flujo lógico de código. Los nombres largos de métodos ocultan sus listas de argumentos igualmente importantes. Las variables largas son molestas por la reutilización, lo que lleva a estirar las cadenas de métodos o cascadas.
Vi nombres de variables de más de 60 caracteres. Puede poner un haiku o koan allí (y probablemente ilumine al lector más que el nombre que elija). Pero no temas, estoy aquí para ayudar.
Elegir un buen nombre
Cualquier nombre en programación tiene dos objetivos:
- El nombre debe ser claro : necesita saber a qué se refiere.
- El nombre debe ser exacto : debe saber a qué no se aplica.
Una vez que el nombre ha alcanzado estos objetivos, los caracteres adicionales son de peso muerto. Aquí hay algunas pautas que uso cuando nombro cosas en mi código:
1. Evite palabras que se especifican explícitamente en una variable o tipo de parámetro
Si su idioma tiene un sistema de tipo estático, los usuarios generalmente conocen el tipo de la variable. Como regla general, los métodos son bastante cortos, por lo que incluso mirar una variable local donde el tipo no se puede asumir de inmediato, o en una revisión de código, o en algún lugar donde el análisis de código estático no puede entrar, rara vez se necesita un poco más que mirar algunas líneas. anterior para determinar el tipo de variable.
Dado esto, no es necesario indicar el tipo en el nombre de la variable. Acabamos de abandonar la notación húngara . Déjate llevar y olvida :
En particular para las colecciones, casi siempre es mejor usar un sustantivo plural que describa el contenido que un sustantivo singular que describa una colección . Si el lector se preocupa más por lo que hay en la colección, entonces el título debe reflejar eso.
Esto también se aplica a los nombres de métodos. El nombre del método no necesita describir sus parámetros o sus tipos; la lista de parámetros lo hará por usted.
Esto da como resultado que las llamadas se lean mejor que esto:
mergeTableCells(tableCells); sortEventsUsingComparator(events, comparator);
¿Soy solo yo, o hay un eco aquí?
2. Evite palabras que no desambiguen el nombre
Algunas personas tienden a poner todo lo que saben sobre algo en el nombre de una variable. Recuerde que el nombre es un identificador : indica el lugar donde está definido. Este no es un catálogo exhaustivo de todo lo que el lector quiera saber sobre el objeto. La definición lo hará mejor. El nombre solo lo dirigirá allí.
Cuando veo el nombre como recentlyUpdatedAnnualSalesBid , me pregunto:
- ¿Hay alguna orden de venta anual actualizada que no sea la última?
- ¿Hay alguna solicitud de venta anual reciente que no se haya actualizado?
- ¿Hay alguna aplicación anual no comercial actualizada recientemente?
- ¿Hay datos de ventas anuales actualizados recientemente que no sean ofertas?
Si la respuesta es "no" a al menos una de estas preguntas, esto generalmente indica una palabra adicional en el nombre.
Por supuesto, puedes ir demasiado lejos. Acortar el primer ejemplo para bid puede ser demasiado vago. Pero si tienes dudas, déjalo así. Siempre puede agregar una clasificación adicional más adelante si el nombre es la causa del conflicto o es inexacto. Sin embargo, es poco probable que regrese más tarde para recortar todo este exceso de grasa.
3. Evite palabras que sean claras por el contexto.
Puedo usar la palabra "I" en este párrafo porque sabes que este texto es de Bob Nystrom. No necesito repetir constantemente "Bob Nystrom" aquí (a pesar de la tentación de Bob Nystrom de fortalecer a Bob Nystrom de esta manera). El código funciona exactamente igual. Un método o campo ocurre en el contexto de una clase. Una variable ocurre en el contexto de un método. Tome este contexto por sentado y no lo repita.
En la práctica, esto significa que cuanto más profundo está incrustado el nombre, más contexto tiene. Como resultado, resulta que este nombre será más corto. Como resultado, puede ver un patrón: los identificadores que están en un área más estrecha tienen nombres más cortos.
4. Evite palabras que no significan nada.
A menudo veo este error en la industria del juego. Algunos desarrolladores sucumben a la tentación e inflan los nombres de sus variables, agregando palabras de "negocios serios". Creen que esto hace que su código sea más importante y, en consecuencia, los hace más importantes.
En la mayoría de los casos, estas palabras no llevan ninguna información significativa para el desarrollador. Por lo general, las sospechas recaen en palabras como: data , state , amount , value , manager , engine , object , entity e instance .
Un buen nombre pinta una imagen en la mente del lector. Al llamar a cualquier cosa un "administrador", no le damos al lector ninguna información sobre lo que debe hacer este objeto. ¿Hace un cálculo de evaluación de desempeño? Nombra promoción a sus empleados?
Pregúntese: "¿Significará este nombre lo mismo si elimino esa palabra?" En caso afirmativo, entonces la palabra no importa: salga de la isla.
Aplicando el manual a ... waffles
Para darle una idea de cómo funcionan estas reglas en la práctica, aquí hay un ejemplo que las viola todas. Este ejemplo artificial es muy similar al código real, que a menudo se me ocurre en la revisión del código.
class DeliciousBelgianWaffleObject { void garnishDeliciousBelgianWaffleWithStrawberryList( List<Strawberry> strawberryList) { ... } }
Gracias al tipo de parámetro, sabemos que el método acepta una lista de fresas (# 1). Cortemos esta información de un nombre:
class DeliciousBelgianWaffleObject { void garnishDeliciousBelgianWaffle( List<Strawberry> strawberries) { ... } }
Si no hay gofres belgas o gofres belgas de cualquier otra nacionalidad en el programa, entonces podemos descartar todos los adjetivos (# 2):
class WaffleObject { void garnishWaffle(List<Strawberry> strawberries) { ... } }
Este método está dentro de WaffleObject , por lo que, por el contexto, sabemos qué decorará exactamente (# 3):
class WaffleObject { void garnish(List<Strawberry> strawberries) { ... } }
Obviamente este es un objeto. Todo es un objeto en la programación orientada a objetos (# 4):
class Waffle { void garnish(List<Strawberry> strawberries) { ... } }
Ahora mucho mejor.
Creo que estas son recomendaciones bastante simples. Tiene derecho a pensar que es inútil preocuparse por tales pequeñeces. Pero creo que nombrar es una de las tareas más fundamentales que realizamos al programar. Los nombres son la estructura que imponemos al mar de bits sin forma, que es la computadora.