¿Cómo puede ser "auto-documentación" el código sin ser molesto? [cerrado]

Question

No estoy seguro de cuáles son las mejores prácticas aquí, pero a menudo veo nombres abreviados de variables, especialmente cuando el alcance es pequeño. Entonces (para usar ejemplos simples de Ruby) en lugar de def add_location (nombre, coordenadas) , veo cosas como def add_loc (name, coord) , y hasta podría ver algo como def add_loc (n, x, y) . Me imagino que los nombres más largos pueden cansar a una persona cuando están acostumbrados a ver las abreviaturas.

¿La verbosidad ayuda a la legibilidad, o simplemente lastima los ojos de todos? ¿Prefieren las abreviaturas y los nombres más cortos que los nombres más largos?

Answer 1

Personalmente, MUCHO preferiría ver nombres más largos que realmente signifiquen algo sin tener que determinar el contexto primero. Por supuesto, las variables que no dan un significado real, como los contadores, todavía uso nombres de variables pequeñas sin sentido (como i o x ), pero por lo demás verbosidad es claridad la mayor parte del tiempo. Esto es especialmente cierto con las API públicas.

Sin embargo, esto puede llevarse demasiado lejos. He visto un código VB en el pasado de esa manera ridícula. La moderación como todo lo demás!

Answer 2

En realidad uso nombres largos de variables todo el tiempo, después de que todos los IDE modernos y los usuarios de mensajes de texto se hayan completado, por lo que no hay nada de malo en usar index en lugar de i. La única excepción que tengo es cuando trato con las coordenadas b / c x y y tienen más sentido allí.

Answer 3

Nunca abbr.

Answer 4

A una variable se le debe dar el nombre más corto posible que transmita adecuadamente su propósito.

La excesiva verbosidad tiende a ocultar la sintaxis, y la sintaxis es importante.

En todo un programa (o aplicación / sistema), las variables deben nombrarse con un estilo consistente y las cosas similares deben nombrarse de manera similar. Si existe una convención dentro de la comunidad lingüística, debe observarse (así que no camelCaseRubyVariableNames) a menos que haya alguna razón convincente para no hacerlo.

Las abreviaturas, si se usan, deben aplicarse consistentemente en todas partes y si son específicas del dominio, deben registrarse en algún lugar. Si alguien va a pasar algún tiempo útil con el código, pronto lo aprenderán.

Si necesita combinar hasta cinco o seis palabras para nombrar una variable, entonces le sugiero que esté mirando un código olor y la rutina que estás trabajando puede beneficiarse de un poco de trabajo.

Sin embargo, en su mayoría, si está al tanto de las dificultades y piensa sobre lo que está escribiendo, lo más probable es que su código sea razonable. Imagínese a sí mismo describiendo la función en la que está trabajando para un nuevo colega: cuanto menos piense que debería decir, mejor será el código.

Answer 5

Intenta leer tu propio código 1 año después. Verá tanto el valor de los nombres de las variables de autodocumentación como el valor de los comentarios de código (y especialmente el valor de código limpio)

Cuando tomas el código fuente de otra persona y no lo entiendes, es fácil pensar "Bueno, él no es tan buen programador como yo" " Pero cuando te das cuenta de que tu propio código es difícil de leer, dices: "¿qué estaba pensando?",

A la larga, la verbosidad ayuda al mantenimiento. Para una secuencia de comandos corta de una línea, aún puede usar " setLocNm " en lugar de setLocationName "

Cualquier tonto puede escribir código que una computadora pueda entender. Los buenos programadores escriben códigos que los humanos pueden entender. -Martin Fowler

Answer 6

Personalmente, considero que la verbosidad es algo bueno, pero también es fácil ser demasiado verboso, lo cual es algo malo. Hay un balance, y las abreviaturas también pueden aparecer en ese balance.

Estas son mis reglas generales:

• Los iteradores pueden ser una letra, es decir. i , j , k , etc.
• Otras variables de una palabra como boolean toggles, que nunca se abrevian, es decir. instalando , hecho , etc.
• Varias variables de palabras y nombres de funciones son candidatos para la abreviatura, pero solo si comienzan a ser ridículamente largos (digamos, 20-25 + caracteres). La abreviatura inteligente es la clave aquí. Función = > func por ejemplo, pero nunca fun , f o functi

Answer 7

Busqué las respuestas, pero no veo si se cubre lo siguiente. Aquí va ...

Ya sea que se abrevie o sea detallado, solo asegúrese de que no haya utilizado más palabras de las necesarias y que el significado sea muy obvio.

Pero incluso después de este filtrado si sus identificadores se ven detallados, tiene un defecto en su diseño.

def initialize_report_template()
end

debería haber sido ...

class ReportTemplate
    def initialize()
    end
end

Answer 8

Los nombres más largos son mucho mejores. Mencionas que a menudo ves nombres abreviados en ámbitos pequeños. ¿Quién dice que el alcance seguirá siendo pequeño a medida que crezca el software?

Por supuesto, XCoordinateForCurrentLocationOfSelf es un nombre ridículo, por lo que debe ser razonable. Especialmente si está entrando a un proyecto en el que no ha trabajado antes, agradecerá a cualquiera que haya usado funciones descriptivas y nombres de variables.

Answer 9

Creo que está bien abreviar cuando el nombre daña la legibilidad o simplemente es redundante.

Ejemplo 1: un argumento de un método donde el tipo ya transmite toda la información necesaria.

Ejemplo 2: una variable que se utilizará mucho de manera obvia

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

Ejemplo 3: Abreviaturas idiomáticas. i, j, k ya ha sido mencionado. " sb " arriba hay uno en nuestro código, y cada equipo probablemente tenga un par más.

Answer 10

Apunte por más corto en vez de por más tiempo, pero la comprensión del lector debe triunfar pereza para escribir cada vez.

Como han dicho otros, la longitud del nombre variable no debería ocultar la lógica o el algoritmo. Por ejemplo, en aritmética, escribimos

( 1 + 5 ) * 3 = 18

en lugar de

three multiplied by the sum of one and five equals eighteen

porque estamos tratando de llamar la atención sobre otras cosas además de la claridad de los elementos involucrados en la expresión.

Tiendo a mantener las variables de una a tres palabras, abreviando solo cuando excedo los 24 caracteres aproximadamente. Cuanto menos frecuentemente se use una variable, es más probable que me sienta en libertad de hacer que el nombre de la variable sea largo. Las variables de uso más frecuente las haré más cortas.

Answer 11

Max Kanat-Alexander, el arquitecto jefe de Bugzilla, dice esto en su blog:

  

El propio código debe ocupar espacio en proporción al significado que tiene.

     

Básicamente, pequeños símbolos que significan una   Muchos hacen que el código sea difícil de leer. Muy largo   nombres que no significan mucho también hacen   Código difícil de leer. La cantidad de   significado y el espacio ocupado debe   estar estrechamente relacionados entre sí.

http://www.codesimplicity.com/post/readability-and -naming-things /

Es una publicación muy perspicaz sobre nombrar cosas. ¡Insto a todos a que lo lean!

Answer 12

La única vez que acepto las abreviaturas es para las variables locales que solo están dentro del alcance durante un pequeño período de tiempo.

Significa que deberían estar dentro del alcance con un método o constructor muy legible.

Answer 13

Estoy de acuerdo con Kilhoffer; Prefiero ver nombres de variables descriptivas en casi todos los contextos. Me abreviaré si los nombres de mis variables tienen más de 20 caracteres, generalmente con palabras en el nombre de la variable (por ejemplo: " SomeVeryLongVarValue ").

Por supuesto, también uso la notación húngara siempre que puedo, por lo que podría estar en el otro extremo de intentar que los nombres de mis variables sean demasiado descriptivos, dependiendo de su perspectiva.

Answer 14

Probablemente me van a abuchear por completo, pero quería asegurarme de que se escuchara esta vista.

Si bien los nombres de variables más largos pueden ser más descriptivos, pueden comenzar a confundir la intención original del programa. Creo que en los elementos de la API es importante tener nombres claros y significativos en el contexto en que se utilizarán.

Dentro de cada función o método, esta es a menudo una historia diferente. Intento escribir menos y mantenerlo muy conciso. Esto se conoce como programación espartana al Sr. Atwood y este ejemplo ingenioso. Sí, el ejemplo está claramente manipulado, pero demuestra cómo tener un poco menos de ceremonia puede facilitar la lectura del programa.

Buena suerte.

Answer 15

Cuando programas, estás utilizando la sintaxis para que los humanos puedan leerla, la longitud de los nombres de las variables, los métodos, etc. son realmente irrevelantes.

De todos modos, cuanto más detallado sea, mejor, con un buen entorno de desarrollo, debería completar el código de todos modos, por lo que simplemente puede presionar " add_L " + TAB para finalizar la llamada al método.

Answer 16

Creo que el principal problema con las abreviaturas es que no todas las personas se abrevian de la misma manera , por lo que cuando se trabaja con muchas personas, solo puede aumentar la probabilidad de error al codificar. Por ejemplo, si tiene una constante que se puede llamar SOMETHING_INTERFACE, tal vez algunos desarrolladores la abreviarán como SOMETHING_INTFACE, otros como SOMETHING_IFACE o SOMETHING_IF, SMTHING_IFACE ...

Con solo dos palabras, puedes tener al menos media docena de más o menos "lógica" posibles abreviaturas, por lo que creo que es mejor en la mayoría de los casos escribir sin abreviaturas y con más razones si desea tener un código auto-documentado.

Los nombres muy largos pueden ser molestos a veces, pero también pueden abreviarse en ámbitos muy locales utilizando variables auxiliares.

Answer 17

La mayoría de las personas leen a primera vista, no se necesita más leer una palabra que leer una letra individual. Así que siempre use nombres significativos. ¿Tienen que ser descripciones completas de 7 palabras, no, pero deben ser lo suficientemente largas para comprender.

Podría aceptar add_loc (nombre, coord), ya que son lo suficientemente largos como para poder decir cuáles son. En add_loc (n, x, y), me opondría a 'n' en lugar del nombre. Podría vivir con X e Y, ya que estos son los nombres de coordenadas aceptados.

Para alguien que no esté familiarizado con los sistemas de coordenadas, podría ver dónde agregar ubicación (nombre, coordenadas) sería más significativo.

En caso de duda, use nombres más largos.

Answer 18

" Está bien descubrir los misterios del asesinato, pero no deberías tener que averiguar el código. Deberías poder leerlo. & Quot; - Steve C. McConnell

Dicho esto, si crees que ni tú ni nadie más necesitan nombres de variables demasiado explícitos, etc., siéntete libre de acortarlos.

Answer 19

Sugiero tomar un enfoque minimalista. Use un poco como sea posible mientras se asegura que su código se mantenga claro, conciso y al punto.

Answer 20

Fuera de alcance, las cosas como las constantes y los globales deben tener nombres descriptivos largos. A veces, un nombre realmente largo lo hará " oler " Lo suficiente como para indicar que su presencia no es deseada. Esto es algo bueno porque puede 1: hacer que la gente lo evite, 2: aumentar la presión para refactorizar el código para que desaparezca.