practices cheatsheet best naming-conventions

naming conventions - cheatsheet - ¿Alguien más considera que las clases y los métodos de denominación son una de las partes más difíciles de la programación?



css convention (30)

¡Invierte en una buena herramienta de refactorización!

Así que estoy trabajando en esta clase que se supone que solicita la documentación de ayuda de un proveedor a través de un servicio web. Intento VendorDocRequester DocumentRetriever , VendorDocRequester , DocGetter , pero simplemente no suenan bien. Terminé navegando por dictionary.com durante media hora tratando de encontrar una palabra adecuada.

Comenzar a programar con nombres malos es como tener un día de cabello muy malo por la mañana, el resto del día va cuesta abajo desde allí. ¿Sienteme?

¿No debería ser la documentación del vendedor el objeto? Quiero decir, ese es tangible, y no solo como una antropomorfización de una parte de su programa. Por lo tanto, es posible que tenga una clase VendorDocumentation con un constructor que recupera la información. Creo que si un nombre de clase contiene un verbo, a menudo algo sale mal.

¿Por qué no HelpDocumentServiceClient una especie de bocado, o HelpDocumentClient ... no importa que sea un proveedor, el punto es que es un cliente de un servicio web que se ocupa de los documentos de Ayuda.

Y sí, nombrar es difícil.

A veces no hay un buen nombre para una clase o método, nos pasa a todos. Sin embargo, muchas veces, la incapacidad de inventar un nombre puede ser un indicio de que algo está mal en su diseño. ¿Tu método tiene demasiadas responsabilidades? ¿Tu clase encapsula una idea coherente?

Convenido. Me gusta mantener los nombres de mi tipo y las variables lo más descriptivos posible sin ser demasiado horrendosamente largos, pero a veces hay un cierto concepto en el que no puedes encontrar una buena palabra.

En ese caso, siempre me ayuda pedirle a un compañero de trabajo que me dé su opinión, incluso si en última instancia no me ayudan, por lo general me ayuda a al menos explicarlo en voz alta y hacer que mis ruedas giren.

Creo que esto es un efecto secundario.

No es el nombre real lo que es difícil. Lo difícil es que el proceso de nombrar te hace enfrentar el horrible hecho de que no tienes idea de qué demonios estás haciendo.

De hecho, acabo de escuchar esta cita ayer, a través del blog Signal vs. Noise en 37Signals, y ciertamente estoy de acuerdo con ello:

"Solo hay dos cosas difíciles en Informática: la invalidación de la memoria caché y nombrar las cosas". - Phil Karlton

Definitivamente te siento. Y siento tu dolor. Todos los nombres que pienso solo me parecen basura. Todo parece tan genérico y, finalmente, quiero aprender a inyectar un poco de estilo y creatividad en mis nombres, haciendo que realmente reflejen lo que describen.

Una sugerencia que tengo es consultar un tesauro. Word tiene una buena, al igual que Mac OS X. Eso realmente puede ayudarme a sacar la cabeza de las nubes y me da un buen punto de partida, así como algo de inspiración.

DocumentFetcher? Es difícil decirlo sin contexto.

Puede ser útil actuar como un matemático y pedir prestado / inventar un léxico para su dominio sobre la marcha: establezca palabras cortas y sencillas que sugieran el concepto sin deletrearlo todo el tiempo. Muy a menudo veo frases largas en latín que se convierten en siglas, lo que hace que necesites un diccionario para las siglas de todos modos .

El lenguaje que usa para describir el problema, es el lenguaje que debe usar para las variables, métodos, objetos, clases, etc. De manera general, los sustantivos coinciden con los objetos y los verbos coinciden con los métodos. Si le faltan palabras para describir el problema, también le falta una comprensión completa (especificación) del problema.

Si se trata simplemente de elegir entre un conjunto de nombres, entonces debe estar impulsado por las convenciones que está utilizando para construir el sistema. Si ha llegado a un lugar nuevo, descubierto por convenciones anteriores, entonces siempre vale la pena dedicar un poco de esfuerzo a tratar de extenderlos (de manera adecuada y coherente) para cubrir este nuevo caso.

En caso de duda, duerma sobre él y elija el primer nombre más obvio a la mañana siguiente :-)

Si un día se despierta y se da cuenta de que estaba equivocado, cámbielo de inmediato.

Pablo.

BTW: Document.fetch () es bastante obvio.

El mes pasado escribí sobre convenciones de nombres: http://caseysoftware.com/blog/useful-naming-conventions

La esencia de esto:

verbAdjectiveNounStructure - con estructura y adjetivo como partes opcionales

Para los verbos , me atengo a los verbos de acción: guardar, eliminar, notificar, actualizar o generar. De vez en cuando, uso "proceso" pero solo para referirme específicamente a colas o trabajos pendientes.

Para los sustantivos , uso la clase u objeto con el que se interactúa. En web2project, esto es a menudo tareas o proyectos. Si es Javascript interactuando con la página, puede ser cuerpo o tabla. El punto es que el código describe claramente el objeto con el que está interactuando.

La estructura es opcional porque es única para la situación. Una pantalla de listado puede solicitar una lista o una matriz. Una de las funciones principales utilizadas en la Lista de proyectos para web2project es simplemente getProjectList. No modifica los datos subyacentes, solo la representación de los datos.

Los adjetivos son algo completamente distinto. Se utilizan como modificadores al sustantivo. Algo tan simple como getOpenProjects podría implementarse fácilmente con un getProjects y un parámetro de cambio, pero esto tiende a generar métodos que requieren un poco de comprensión de los datos subyacentes y / o la estructura del objeto ... no necesariamente algo que desee animar. Al tener funciones más explícitas y específicas, puede ajustar y ocultar completamente la implementación del código que lo utiliza. ¿No es ese uno de los puntos de OO?

Es bueno que sea difícil. Te obliga a pensar sobre el problema y lo que la clase realmente debe hacer. Los buenos nombres pueden ayudar a conducir a un buen diseño.

Esta es una de las razones para tener un estándar de codificación. Tener un estándar tiende a ayudar a inventar nombres cuando es necesario. ¡Ayuda a liberar tu mente para usar para otras cosas más interesantes! (-:

Recomiendo leer el capítulo relevante del Código Completo de Steve McConnell ( enlace de Amazon ) que incluye varias reglas para facilitar la lectura e incluso la capacidad de mantenimiento.

HTH

aclamaciones,

Robar

Hilo 1:

function programming_job(){ while (i make classes){ Give each class a name quickly; always fairly long and descriptive. Implement and test each class to see what they really are. while (not satisfied){ Re-visit each class and make small adjustments } } }

Hilo 2:

while(true){ if (any code smells bad){ rework, rename until at least somewhat better } }

No hay Thread.sleep (...) en ningún lugar aquí.

Leo Brodie, en su libro "Thinking Forth", escribió que la tarea más difícil para un programador era nombrar bien las cosas, y afirmó que la herramienta de programación más importante es un tesauro.

Intente usar el diccionario de sinónimos en http://thesaurus.reference.com/ .

Más allá de eso, no utilice la notación húngara NUNCA, evite las abreviaturas y sea coherente.

Los mejores deseos.

Lo que estás haciendo ahora está bien, y te recomiendo que te quedes con tu sintaxis actual, ya que:

contexto + verbo + cómo

Utilizo este método para nombrar funciones / métodos, procedimientos almacenados de SQL, etc. Al mantener esta sintaxis, mantendrá su Intellisense / Code Panes mucho más ordenado. Así que quieres EmployeeGetByID () EmployeeAdd (), EmployeeDeleteByID (). Cuando use una sintaxis gramaticalmente más correcta, como GetEmployee (), AddEmployee () verá que esto se vuelve realmente complicado si tiene múltiples Gets en la misma clase, ya que las cosas no relacionadas se agruparán.

Me refiero a nombrar archivos con fechas, quiere decir 2009-01-07.log no 1-7-2009.log porque después de tener un montón de ellos, el orden se vuelve totalmente inútil.

Más que solo nombrar una clase, crear un paquete apropiado puede ser un desafío difícil pero gratificante. Debe considerar separar las preocupaciones de sus módulos y cómo se relacionan con la visión de la aplicación.

Considera el diseño de tu aplicación ahora:

  • Aplicación
    • VendorDocRequester (leer del servicio web y proporcionar datos)
    • VendorDocViewer (use el solicitante para proporcionar documentos del proveedor)

Me atrevería a adivinar que hay muchas cosas dentro de algunas clases. Si tuviera que refactorizar esto en un enfoque más basado en MVC, y permitir que las clases pequeñas se encarguen de tareas individuales, podría terminar con algo como:

  • Aplicación
    • VendorDocs
      • Modelo
        • Documento (objeto plano que contiene datos)
        • WebServiceConsumer (tratar con nitty gritty en servicio web)
      • Controlador
        • DatabaseAdapter (manejar la persistencia usando ORM u otro método)
        • WebServiceAdapter (utilizar el consumidor para tomar un documento y pegarlo en la base de datos)
      • Ver
        • HelpViewer (use DBAdapter para escupir la documentación)

Luego, los nombres de sus clases dependen del espacio de nombres para proporcionar un contexto completo. Las clases en sí pueden estar inherentemente relacionadas con la aplicación sin necesidad de decirlo explícitamente. ¡Los nombres de clase son más simples y fáciles de definir como resultado!

Otra sugerencia muy importante: hazte un favor y recoge una copia de Head First Design Patterns. Es un libro fantástico de fácil lectura que te ayudará a organizar tu aplicación y escribir mejor código. Apreciar los patrones de diseño lo ayudará a comprender que muchos de los problemas que encuentra ya se han resuelto, y podrá incorporar las soluciones a su código.

Me atengo a lo básico: VerbNoun (argumentos). Ejemplos: GetDoc (docID).

No hay necesidad de ser elegante. Será fácil de entender dentro de un año, ya sea usted o alguien más.

Me parece que tengo más problemas en las variables locales. Por ejemplo, quiero crear un objeto de tipo DocGetter. Así que sé que es un DocGetter. ¿Por qué necesito darle otro nombre? Normalmente termino dándole un nombre como dg (para DocGetter) o temp o algo igualmente indescriptivo.

No olvide que los patrones de diseño (no solo los GoF) son una buena manera de proporcionar un vocabulario común y sus nombres deben usarse siempre que se adapte a la situación. Eso ayudará incluso a los recién llegados que están familiarizados con la nomenclatura a comprender rápidamente la arquitectura. ¿Se supone que esta clase en la que estás trabajando debe actuar como un Proxy, o incluso una Fachada?

No, la depuración es lo más difícil para mí! :-)

Para mí no me importa cuánto tiempo un método o nombre de clase es tan largo como descriptivo y en la biblioteca correcta. Atrás quedaron los días en los que deberías recordar dónde reside cada parte de la API.

Intelisense existe para todos los idiomas principales. Por lo tanto, cuando utilizo una API de terceros, me gusta usar su intelisense para la documentación en lugar de usar la documentación "real".

Teniendo eso en cuenta, estoy bien para crear un nombre de método como

StevesPostOnMethodNamesBeingLongOrShort

Largo, pero ¿y qué? ¿Quién no usa pantallas de 24 pulgadas en estos días!

Si el nombre se explicara a un programador lego, entonces probablemente no hay necesidad de cambiarlo.

Solo hay un nombre sensible para esa clase:

HelpRequest

No permita que los detalles de la implementación lo distraigan del significado.

También paso mucho tiempo preocupándome por los nombres de cualquier cosa a la que pueda darme un nombre cuando estoy programando. Yo diría que vale la pena muy bien sin embargo. A veces, cuando estoy atascado, lo dejo por un tiempo y durante un descanso para tomar un café pregunto un poco si alguien tiene una buena sugerencia.

Para su clase sugeriría VendorHelpDocRequester .

Tengo que aceptar que nombrar es un arte. Se vuelve un poco más fácil si su clase sigue un cierto "patrón de desigh" (fábrica, etc.).

Una buena convención de nomenclatura debe minimizar el número de nombres posibles que puede usar para cualquier variable, clase, método o función dada. Si solo hay un nombre posible, nunca tendrás problemas para recordarlo.

Para las funciones y para las clases singleton, examino la función para ver si su función básica es transformar un tipo de cosa en otro tipo de cosa. Estoy usando ese término muy a la ligera, pero descubrirá que un número enorme de funciones que escribe esencialmente toma algo en una forma y produce algo en otra forma.

En su caso, suena como que su clase transforma una URL en un documento. Es un poco extraño pensar de esa manera, pero perfectamente correcto, y cuando empieces a buscar este patrón, lo verás en todas partes.

Cuando encuentro este patrón, siempre nombro la función x From y .

Ya que su función transforma una URL en un documento, yo la llamaría

DocumentFromUrl

Este patrón es muy común. Por ejemplo:

atoi -> IntFromString GetWindowWidth -> WidthInPixelsFromHwnd // or DxFromWnd if you like Hungarian CreateProcess -> ProcessFromCommandLine

También puede usar UrlToDocument si está más cómodo con ese pedido. Si dices x From y o y To x es probablemente una cuestión de gustos, pero prefiero el orden From porque de esa manera el principio del nombre de la función ya te dice qué tipo devuelve.

Elige una convención y apégate a ella. Si tiene cuidado de usar los mismos nombres que sus nombres de clase en sus funciones x From y , será mucho más fácil recordar qué nombres usó. Por supuesto, este patrón no funciona para todo, pero funciona cuando se escribe un código que se puede considerar como "funcional".

Una lección que aprendí es que si no puedes encontrar un nombre para una clase, casi siempre hay algo mal con esa clase:

  • no lo necesitas
  • hace demasiado

En breve:
Estoy de acuerdo en que los buenos nombres son importantes, pero no creo que deban encontrarlos antes de implementar a toda costa.

Por supuesto, es mejor tener un buen nombre desde el principio. Pero si no puede crear uno en 2 minutos, cambiar el nombre más tarde costará menos tiempo y es la opción correcta desde el punto de vista de la productividad.

Largo:
En general, a menudo no vale la pena pensar demasiado en un nombre antes de implementar. Si implementas tu clase, dale el nombre "Foo" o "Dsnfdkgx", mientras implementas, verás lo que deberías haber llamado.

Especialmente con Java + Eclipse, cambiar el nombre de las cosas no es un problema, ya que maneja con cuidado todas las referencias en todas las clases, le advierte sobre colisiones de nombres, etc. Y mientras la clase no esté en el repositorio de control de versiones, no lo haré. No creo que haya nada de malo en cambiarle el nombre 5 veces.

Básicamente, es una cuestión de cómo piensas sobre la refactorización. Personalmente, me gusta, aunque a veces molesta a mis compañeros, ya que creen que nunca tocan un sistema en ejecución . Y de todo lo que puede refactorizar, cambiar de nombre es una de las cosas más inofensivas que puede hacer.