¿Hay una excusa para nombres cortos de variables?

Esto se ha convertido en una gran frustración con la base de código en la que estoy trabajando actualmente; Muchos de nuestros nombres de variables son cortos y no descriptivos. Soy el único desarrollador que queda en el proyecto, y no hay documentación sobre lo que hacen la mayoría de ellos, por lo que tengo que dedicar más tiempo para rastrear lo que representan.

Por ejemplo, estaba leyendo sobre un código que actualiza la definición de una superficie óptica. Las variables establecidas al inicio fueron las siguientes:

double dR, dCV, dK, dDin, dDout, dRin, dRout
dR = Convert.ToDouble(_tblAsphere.Rows[0].ItemArray.GetValue(1));
dCV = convert.ToDouble(_tblAsphere.Rows[1].ItemArray.GetValue(1));
... and so on

Tal vez soy solo yo, pero esencialmente no me dijo nada sobre lo que representaban, lo que dificultó la comprensión del código más abajo. Todo lo que sabía era que era una variable analizada en una fila específica de una tabla específica, en algún lugar. Después de buscar un poco, descubrí lo que significaban:

dR = radius
dCV = curvature
dK = conic constant
dDin = inner aperture
dDout = outer aperture
dRin = inner radius
dRout = outer radius

Les cambié el nombre a esencialmente lo que tengo allí arriba. Alarga algunas líneas, pero siento que es un intercambio justo. Sin embargo, este tipo de esquema de nombres se utiliza en gran parte del código. No estoy seguro de si es un artefacto de los desarrolladores que aprendieron trabajando con sistemas más antiguos, o si hay una razón más profunda detrás de esto. ¿Hay una buena razón para nombrar variables de esta manera, o estoy justificado para actualizarlas a nombres más descriptivos a medida que las encuentro?

Parece que estos nombres de variables se basan en las abreviaturas que esperaría encontrar en un libro de texto de física que resuelve varios problemas de óptica. Esta es una de las situaciones en las que los nombres de variables cortos a menudo son preferibles a los nombres de variables más largos. Si tiene físicos (o personas que están acostumbradas a resolver las ecuaciones a mano) que están acostumbrados a usar abreviaturas comunes como Rin, Rout, etc., el código será mucho más claro con esas abreviaturas de lo que sería con nombres de variables más largos. También hace que sea mucho más fácil comparar fórmulas de documentos y libros de texto con código para asegurarse de que el código realmente esté haciendo los cálculos correctamente.

Cualquiera que esté familiarizado con la óptica reconocerá de inmediato algo como Rin como el radio interno (en un documento de física, inse representaría como un subíndice), Rout como el radio externo, etc. Aunque es casi seguro que puedan traducir mentalmente algo Al igual que innerRadiuscon la nomenclatura más familiar, hacerlo haría que el código sea menos claro para esa persona. Haría más difícil detectar casos en los que una fórmula familiar se hubiera codificado incorrectamente y haría más difícil traducir ecuaciones en código hacia y desde las ecuaciones que encontrarían en un documento o en un libro de texto.

Si usted es la única persona que mira este código, nunca necesita traducir entre el código y una ecuación óptica estándar, y es poco probable que un físico vaya a necesitar mirar el código en el futuro, tal vez sí lo haga. tiene sentido refactorizar porque el beneficio de las abreviaturas ya no supera el costo. Sin embargo, si se tratara de un nuevo desarrollo, seguramente tendría sentido usar las mismas abreviaturas en el código que encontraría en la literatura.

Las variables con vidas cortas deben nombrarse en breve. Como ejemplo, no escribes for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { .... En cambio, lo usas for(int i ....

En general, se podría decir que cuanto más corto sea el alcance de la variable, más corto debería ser el nombre. Contadores de bucles son a menudo sólo letras individuales, dicen i, jy k. Las variables locales son algo como baseo fromy to. Las variables globales son algo más elaboradas, por ejemplo EntityTablePointer.

Quizás una regla como esta no se sigue con la base de código con la que trabaja. ¡Sin embargo, es una buena razón para refactorizar!

El problema con el código no son los nombres cortos, sino la falta de un comentario que explique las abreviaturas o señale algunos materiales útiles sobre las fórmulas de las cuales se derivan las variables.

El código simplemente asume la familiaridad del dominio del problema.

Eso está bien, ya que probablemente se requiera familiaridad con el dominio del problema para comprender y mantener el código, especialmente en el papel de alguien que lo "posee", por lo que le corresponde adquirir la familiaridad en lugar de andar alargando los nombres.

Pero sería bueno si el código proporcionara algunos consejos para servir como trampolines. Incluso un experto en dominios podría olvidar que dKes una constante cónica. Agregar una pequeña "hoja de trucos" en un bloque de comentarios no estaría de más.

Para ciertas variables que son bien conocidas en el dominio del problema, como el caso que tiene aquí, los nombres de variables concisos son razonables. Si estoy trabajando en un juego, quiero que mis entidades de juego tengan variables de posición xy y, no horizontalPositiony verticalPosition. Asimismo contadores de bucles que no tienen ningún semántica más allá de indexación, que esperan ver i, j, k.

Según el "Código limpio":

Los nombres de las variables deberían:

• Se intencional revelando
• Evitar la desinformación
• Hacer distinciones significativas
• Ser pronunciable
• Ser buscable

Las excepciones son los proverbiales i,j,k,m,nutilizados para bucles.

La variable te nombra, con razón, te quejas de no hacer nada de lo anterior. Esos nombres son malos nombres.

Además, como todos los métodos deben ser cortos , el uso de prefijos para indicar el alcance o el tipo ya no está en uso.

Estos nombres son mejores:

radius
curvature
conicConstant
innerAperture
outerAperture
innerRadius
outerRadius

Un comentarista dice que esto sería demasiado complejo con nombres de variables largos:

Los nombres cortos de variables tampoco lo hacen simple:

fnZR = (r^2/fnR(1+Math.sqrt((1+k) * (r^2/R^2)))) + a[1]*r^2 + a[1]*r^4 + a[1]*r^6 ...;

La respuesta son nombres largos y resultados intermedios hasta que obtenga esto al final:

thisNiceThing =  ( thisOKThing / thisGreatThing ) + thisAwsomeThing;

Hay dos buenas razones para no cambiar el nombre de las variables en el código heredado.

(1) a menos que esté utilizando una herramienta de refactorización automatizada, la posibilidad de introducir errores es alta. Por lo tanto, "si no está roto, no lo arregles"

(2) hará que sea imposible comparar versiones actuales con versiones anteriores para ver qué cambió. Esto hará que el mantenimiento futuro del código sea más difícil.

¿Hay una buena razón para nombrar variables de esta manera, o estoy justificado para actualizarlas a nombres más descriptivos a medida que las encuentro?

La razón para usar nombres más pequeños es si el programador original les resulta más fácil trabajar con ellos. Presumiblemente, tienen el derecho de determinar que ese sea el caso, y el derecho de no tener las mismas preferencias personales que usted tiene. Personalmente, encontraría ...

dDin better than dDinnerAperture
dDout better than dDouterAperture

... si los estuviera usando en cálculos largos y complejos. Cuanto más pequeña es la expresión matemática, a menudo es más fácil ver todo de una vez. Aunque si ese fuera el caso, podrían ser mejores como dIn y dOut, por lo que no había una D repetitiva que pudiera conducir a un error tipográfico fácil.

Por otro lado, si le resulta más difícil trabajar con él, elimínelo y cambie el nombre a su forma más larga. Especialmente si eres responsable de ese código.

En general, creo que la regla para esto debería ser que puede usar nombres de variables extremadamente cortos donde sepa que las personas que son "expertas en el arte" de su código particular entenderán inmediatamente la referencia de ese nombre de variable. (Siempre tiene comentarios para la excepción de este caso de todos modos), y que el uso localizado de las variables se puede discernir fácilmente en función del contexto de cómo se usan.

Para ampliar esto, significa que no debe salir de su camino para ofuscar sus nombres de variables, pero puede usar abreviaturas para sus nombres de variables, donde sabe que solo las personas que entienden el concepto subyacente de su código son probables para leerlo de todos modos.

Para usar un ejemplo del mundo real, recientemente, estaba creando una clase de Javascript que tomaría una latitud y le diría la cantidad de luz solar que esperaría en una fecha determinada.

Para crear esta clase de reloj de sol , me referí a una media docena de recursos, el Astronomy Almanac y fragmentos de otros lenguajes (PHP, Java, C, etc.).

En casi todos estos, usaron abreviaturas idénticas similares, que a primera vista no significan absolutamente nada.

K` T` EPS` deltaPsi` eot` LM`RA

Sin embargo, si tiene conocimientos de física, puede comprender cuáles eran. No esperaría que nadie más tocara este código, entonces, ¿por qué usar nombres de variables detallados?

julianTime` nutationOfEclipticalLongitudeExpressedInDegrees` equationOfTime` longitudeMean` rightAscension.

Además, muchas veces, cuando los nombres de las variables son transitorios, es decir, solo se usan para asignar temporalmente algún valor, entonces con frecuencia no tiene sentido usar una versión detallada, especialmente cuando el contexto de la variable explica su propósito.

Absolutamente lo hay; a menudo un nombre de variable corto es todo lo que se necesita.

En mi caso, estoy haciendo navegación de puntos de referencia en mi clase senior de robótica, y programamos nuestros robots en KISS-C. Necesitamos variables para las coordenadas actuales y de destino (x, y), distancias (x, y), encabezados actuales y de destino, así como ángulos de giro.

Especialmente en el caso de las coordenadas xey, un nombre de variable largo es completamente innecesario, y nombres como xC (actual x), yD (destino y) y pD (phi de destino) son suficientes y son los más fáciles de entender. en este caso.

Podría argumentar que estos no son 'nombres de variables descriptivas' como lo dictaría el protocolo del programador, pero dado que los nombres se basan en un código simple (d = destino, c = actual), un comentario muy simple al principio es toda la descripción ellos requieren.

¿Hay una buena razón para nombrar variables de esta manera, o estoy justificado para actualizarlas a nombres más descriptivos a medida que las encuentro?

Por lo general, los algoritmos complejos se implementan en matlab (o lenguaje similar). Lo que he visto es que las personas simplemente toman el nombre de las variables. De esa manera, es simple comparar implementaciones.

Todas las demás respuestas son casi correctas. Estas abreviaturas se pueden encontrar en matemáticas y física, excepto que no comienzan con d(como en su ejemplo). Las variables que comienzan con d generalmente se nombran para representar la diferenciación .

Todas las guías de codificación normales indican que no se nombren las variables con la primera letra que representa el tipo (como en su caso), porque es muy fácil explorar el código en todos los IDE modernos.

Se me ocurre una razón para que los nombres de las variables sean razonablemente cortos.

Los nombres cortos son fáciles de leer usando un espacio de ojos más corto, por lo tanto, un período de atención corto.

Por ejemplo, una vez que me acostumbro al hecho de que svdb significa "guardar en la base de datos", la velocidad de escaneo del código fuente mejora, ya que solo tengo que escanear rápidamente 4 caracteres en lugar de leer SaveToDatabase (14 caracteres, las cosas empeoran para nombres de operaciones más complejas). Digo "escanear", no "leer", porque eso toma una parte importante del análisis del código fuente.

Al escanear a través de una gran cantidad de código fuente, esto puede proporcionar buenas ganancias de rendimiento.

Además, solo ayuda al programador perezoso a escribir estos nombres cortos al escribir código.

Por supuesto, se espera que todos estos "shorthands" estén listados en alguna ubicación estándar en el código fuente.

Para enmarcar lo que @zxcdw dijo de una manera ligeramente diferente, y elaborarlo en términos de enfoque:

Las funciones deben ser puras , breves y una perfecta encapsulación de algunas funciones: lógica de caja negra , independientemente de si ha estado intacta durante 40 años, continuará haciendo el trabajo para el que fue diseñada, debido a su interfaz (entrada y salida) es sonido, incluso si no sabes nada de sus partes internas.

Este es el tipo de código que desea escribir: este es un código que dura y es fácil de portar.

Cuando sea necesario, componga funciones a partir de otras llamadas de función (en línea) , para mantener el código detallado.

Ahora, con un nombre de función adecuadamente descriptivo (¡detallado si es necesario!), Minimizamos cualquier posibilidad de mala interpretación de esos nombres de variables acortados, ya que el alcance es muy pequeño.

Los nombres de las variables deben ser lo más descriptivos posible para ayudar a la legibilidad del programa. Usted mismo lo experimentó: tuvo muchos problemas para identificar lo que hizo el programa debido a la mala denominación.

No hay una buena razón para no usar un nombre descriptivo. Le ayudará a usted y a todos los que trabajan / trabajarán en el proyecto. Bueno, en realidad hay un único uso válido para nombres cortos: contadores de bucles.

¿Seguramente para eso son // los comentarios?

Si las tareas tienen comentarios que son descriptivos, obtienes lo mejor de ambos mundos: una descripción de la variable y cualquier ecuación son fácilmente comparables con su contraparte de libro de texto.

Para las interfaces (por ejemplo, firmas de métodos, firmas de funciones) tiendo a resolver esto anotando las declaraciones de parámetros. Para C / C ++, esto decora el archivo .h, así como el código de la implementación.

Hago lo mismo para las declaraciones de variables donde conocer el uso de la variable no es obvio en contexto y en el nombre. (Esto también se aplica en idiomas que no tienen una escritura fuerte).

Hay muchas cosas que no queremos obstruir el nombre de la variable. Es el ángulo en radianes o grados, hay cierta tolerancia en la precisión o el rango, etc. La información puede proporcionar afirmaciones valiosas sobre características que deben tratarse correctamente.

No soy religioso al respecto. Simplemente estoy interesado en la claridad y en asegurarme de saber qué es la próxima vez que mi olvidadizo visite el código. Y cualquiera que mire por encima de mi hombro tiene lo que necesita saber para ver dónde está algo apagado, lo que es esencial (lo último crítico para un mantenimiento adecuado).

¿Hay una excusa para nombres de variables excesivamente cortos?

Primero: nombrar una variable para la energía e mientras se calculan fórmulas como E = MC2 NO es un nombre excesivamente corto. Usar símbolos como argumento para nombres cortos no es válido

Esta pregunta me resultó bastante interesante, y solo puedo pensar en una excusa y es el dinero.

Digamos, por ejemplo, que está conectando javascript para un cliente que sabe que el archivo debe descargarse muchas veces por segundo. Sería más barato y mejoraría la experiencia de los usuarios si el archivo (en número de bytes) es lo más pequeño posible.

(Solo para mantener el ejemplo 'realista', no se le permitió usar una herramienta de minificador, ¿por qué? Problemas de seguridad, no se permiten herramientas externas para tocar la base del código).

Noto que las otras respuestas no mencionan el uso de la notación húngara. Esto es ortogonal al largo debate, pero relevante para los esquemas de nombres en general.

double dR, dCV, dK, dDin, dDout, dRin, dRout

La "d" al comienzo de todas estas variables está destinada a indicar que son dobles; pero el lenguaje hace cumplir esto de todos modos. A pesar de la brevedad de estos nombres, ¡son hasta un 50% redundantes !

Si vamos a usar una convención de nomenclatura para reducir los errores, es mucho mejor codificar la información que el idioma no está verificando. Por ejemplo, ningún idioma se quejará dK + dRen el código anterior, aunque no tenga sentido agregar un número adimensional a una longitud.

Una buena manera de prevenir tales errores es usar tipos más fuertes; sin embargo, si vamos a usar dobles, entonces un esquema de nombres más apropiado podría ser:

// Dimensions:
// l  = length
// rl = reciprocal length
double lR, rlCV, K, lDin, lDout, lRin, lRout

El idioma aún nos permitirá escribir K + lR, pero ahora los nombres nos dan una pista de que esto podría ser incorrecto.

Esta es la diferencia entre sistemas húngaros (generalmente malos) y aplicaciones húngaros (posiblemente buenos)

http://en.wikipedia.org/wiki/Hungarian_notation

El único caso donde los nombres de variables ilegiblemente cortos son aceptables en la ingeniería de software moderna es cuando existen en un script y el rendimiento de ese script (en una red en general) es importante. Incluso entonces, mantenga el script con nombres largos en el control de origen y minimice el script en producción.