Directrices concisas significativas para nombrar métodos

Recientemente comencé a lanzar un proyecto de código abierto, aunque era el único usuario de la biblioteca, no me importaban los nombres, pero sé que quiero asignar nombres inteligentes a cada método para que sea más fácil de aprender, pero también necesito usar nombres concisos para que también sean fáciles de escribir.

Estaba pensando en algunas pautas sobre el nombre, estoy al tanto de muchas pautas que solo se preocupan por el uso de letras o algunas notas simples. Aquí, busco pautas para nombres significativos pero concisos.

Por ejemplo, esto podría ser parte de las pautas que estoy cuidando:

• Use Agregar cuando se vaya a agregar un elemento existente a un objetivo, Use Crear cuando se cree un nuevo elemento y se agregue a un objetivo.
• Use Eliminar cuando un elemento existente se vaya a eliminar de un objetivo, Use eliminar cuando un elemento se vaya a eliminar permanentemente.
• Empareje los métodos AddXXX con RemoveXXX y Empareje los métodos CreateXXX con los métodos DeleteXXX, pero no los mezcle.

Como muestran los ejemplos anteriores, me gustaría encontrar material en línea que me ayude con los métodos de denominación y otros elementos que cumplan con la gramática inglesa y el significado de las palabras.

La guía anterior puede ser intuitiva para hablantes nativos de inglés, pero para mí que el inglés es mi segundo idioma, necesito que me digan cosas como esta.

Naming Una de las cosas más difíciles sobre el desarrollo de software :)

Cuando nombre algo, aquí está mi conjunto de prioridades:

• Sigue los modismos de mi idioma. A Ruby le gustan los guiones bajos. A Javascript le gusta la funda de camello. Cualquiera sea el idioma en el que se encuentre, es la convención a seguir.
• Revela la intención de la API. No es "send_http_data" es "post_twitter_status"
• Evite filtrar detalles de implementación. Digamos, anteponiendo una variable con un tipo.
• No utiliza más caracteres de los necesarios sin romper las pautas anteriores.

Obviamente, este es un enfoque bastante simplista. Nombrar es matizado.

Para futuras investigaciones, recomendaría leer The Art of Readable Code , ya que proporciona algunos consejos excelentes y concisos sobre la denominación de métodos. Para aún más investigación, no puedo recomendar el Código Limpio de Bob Martin

La tentación de codificar un estilo o una convención para nombrar puede en algunos casos conducir a hábitos que hoy en día se consideran malas prácticas, como el uso de la notación húngara, por ejemplo. La respuesta simple es olvidarse de la convención y estilo de nomenclatura como si fuera algo separado que se determinará por separado, y en su lugar centrarse en nombrar todo en su sistema en función de lo que realmente representa. Los nombres de los métodos serán naturalmente concisos si limita la funcionalidad de cada método de modo que solo haga una cosa teóricamente, y si el nombre de su método realmente describe la única cosa que se supone que debe hacer.

Las variables, los campos, los nombres de clase y archivo son otra cosa. Sugeriría que si los nombres de las variables son demasiado largos, entonces está intentando describir estos elementos con demasiado detalle, o representan algo complejo que debería dividirse en partes más pequeñas o tal vez descritas en un resumen más abstracto. manera.

Al final del día, desea evitar el código feo con nombres que ocupan una fila completa, o que son tan sencillos como para robarles su valor.

Para mí, encontrar un buen nombre para algo siempre vuelve a pensar en él como un objeto que tiene que justificar su existencia. Pregúntese:

• ¿Qué hace la clase / método / variable, es decir, cuál es su propósito más amplio y para qué sirve?
• ¿Qué tiene que decir específicamente sobre su propósito para comunicarse, es decir, cuál es la parte esencial que debe tener el nombre?

La mayoría de los desarrolladores estarían de acuerdo en que la legibilidad siempre es de suma importancia cuando se trata de nombrar. No solo escriba código para que sepa lo que quiere decir mientras lo escribe, escríbalo para que alguien que vea el código por primera vez en algún momento en el futuro sepa lo que quiere decir sin tener que pensar demasiado. Escribirás el código solo una vez, pero durante su vida probablemente tendrá que editarlo muchas veces y leerlo aún más.

El código debe autodocumentarse, es decir, su nombre debería hacer obvio lo que hace algo. Si necesita explicar lo que hace una línea de código en un comentario, y cambiar el nombre de las cosas no mejora lo suficiente, debería considerar seriamente refactorizar esa línea en un nuevo método con un nombre descriptivo apropiado, de modo que al leer el método original, el La nueva llamada al método describe lo que está sucediendo. No tengas miedo de tener nombres largos; por supuesto, no deberías escribir novelas en nombres de clase / método / variable, pero prefiero que un nombre sea demasiado largo y descriptivo que demasiado corto y necesito averiguar qué hace mirando debajo del capó. Excepto por algunas excepciones obvias, como las coordenadas x / y y los acrónimos de uso común, evite los nombres y abreviaturas de un solo carácter. Llamar a algo "bkBtn" en lugar de "backButton"

Tanto como lo permita su idioma, haga que su código se lea como una oración en inglés. Los objetos usan sustantivos, los métodos usan verbos. Los métodos booleanos generalmente comienzan con "es", pero hay muchas otras opciones que transmiten el significado aún mejor, dependiendo del caso de uso, como "puede", "debería" o "hace". Por supuesto, no todos los idiomas pueden ser tan buenos como Smalltalk en esto, pero algunos símbolos generalmente se entienden como partes de la oración. Dos convenciones de Smalltalk que personalmente me gusta llevar a otros idiomas tanto como sea posible son prefijar el nombre de los parámetros de bucle con "cada", y prefijar los parámetros del método con el artículo "a" (o "an", o "algunos" para colecciones) . Esto puede no ser un estándar común en Java, y cualquiera puede ignorar este bit, pero encuentro que esto mejora enormemente la legibilidad del código. Por ejemplo (ejemplo en Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Esto debería ser legible para las personas con un poco de conocimiento de Java como algo así:

Para determinar si debe considerar abreviar una lista de algunos nombres (que son cadenas), repita algunos nombres y, para cada nombre, determine si es demasiado largo; si es así, regrese true; si ninguno es demasiado largo, regrese false.

Contraste el código anterior con solo nombrar el argumento stringsy la variable de bucle string, especialmente en un método más complejo. Tendría que mirar de cerca para ver la diferencia en lugar de que el uso sea obvio de un vistazo al nombre.

Encontrar un buen nombre siempre es un compromiso entre más factores. Nunca estarás completamente satisfecho.

Dicho esto, incluso si su idioma nativo no es así, considere que el inglés es el idioma cuyos tokens de lenguajes de programación se forman. El uso de una sintaxis similar al inglés hace que la lectura de códigos sea más "fluida" ya que no hay "reglas de lectura rotas" cada vez que se encuentra una palabra clave.

En general, considere cosas como object.method(parameters)hacer coincidir un esquema como subject.verb(complements).

El punto clave, si tiene que soportar programación genérica, es elegir un conjunto de "verbos" bueno y consistente (especialmente los que necesitan ser usados ​​en algoritmos genéricos).

Acerca de los sustantivos, las clases deben nombrarse por lo que ellos are(en términos de concepto), mientras que los objetos por lo que ellos are for.

Dicho esto, entre list.add(component)y component.add_to(list)prefiero el primero. En general, los verbos "activos transitivos" representan mejor las acciones con respecto a sus contrapartes pasivas o reflexivas. A menos que las restricciones de diseño lo persigan.

No se preocupe por la longitud de los nombres de los métodos. Asegúrese de que los nombres de los métodos reflejen claramente lo que están haciendo. Esto es primordial para cualquier otra cosa. Si cree que el nombre del método es demasiado largo, use un diccionario de sinónimos para encontrar una palabra más corta que signifique lo mismo. Por ejemplo, use en Findlugar de Retrieve.

Además, lo que es igual de importante son los nombres que elija para sus clases. Estos proporcionan mucho contexto al mirar los nombres de los métodos. Una firma de método como esta:

public User Find(int userId);

es más fácil de entender que:

public Person Find(int personId);

porque el contexto obtenido del nombre de la clase Userle dice al programador que Find()es para localizar un tipo específico de persona, el usuario de su sistema. La versión que usa la Personclase no le da ningún contexto sobre por qué incluso necesitaría usar el método en primer lugar.

Observe cómo lo hacen otros en su plataforma: algunos de los jugadores más grandes pueden incluso tener estilo de código y pautas de nomenclatura.

Algunas plataformas prefieren nombres cortos (por ejemplo, en la API Win32 C _tcsstres la función para encontrar una cadena dentro de una cadena, ¿no es obvio?), Otras apuestan por la legibilidad a favor de la brevedad (en el marco Cocoa de Apple para Objective-C , el método para reemplazar una subcadena en una cadena con otra cadena y devolver el resultado cuando se llama una copia stringByReplacingOccurrencesOfString: withString:). Encuentro que este último es mucho más fácil de entender y solo moderadamente más difícil de escribir (especialmente con la finalización del código).

Como lee el código con más frecuencia de lo que lo escribe (doblemente cierto para las bibliotecas de código abierto), y leer es más difícil que escribir, optimice para leer. Optimice la brevedad solo al final, y retire solo la mayor cantidad posible sin diluir la claridad.

1. Asuma inglés, a menos que cada desarrollador que alguna vez trabaje en este código hable el mismo idioma que no sea inglés.

2. Estudie las convenciones y estilos de denominación comúnmente aceptados. Su principio rector debe ser la claridad. Los estilos difieren según el lenguaje de programación.

3. No hay nada que pueda hacer con los nombres que haga que sea más fácil entender las relaciones entre los diversos objetos en su código. Para eso, aún necesita comentarios y documentación bien escritos.

1. Usar prefijo Si se utilizan varios métodos para hacer algo similar o se pueden agrupar de alguna manera, coloque un prefijo común antes de sus nombres para mostrar qué tienen en común estos métodos.
2. No use abreviaturas poco claras si desea que otros comprendan los nombres al instante (importante en los nombres de API)