¿Dónde poner un glosario de términos y patrones importantes en la documentación? [cerrado]

Question

Saludos.

Quiero documentar ciertos patrones en el código con el fin de construir una terminología coherente (con el fin de la comunicación easen sobre el software). Estoy, sin embargo, no está seguro, donde para definir los términos dados. Con el fin de obtener en el mismo nivel, un ejemplo:

Tengo un generador de código. Este generador de código recibe una cierta InputStructure del Analizador (sí, el nombre InputStructure podría ser menos que ideal). Este InputStructure se transforma entonces en diversas estructuras de datos posteriores (como una descripción abstracta del proceso de validación). Cada una de estas estructuras de datos pueden ser transformados o bien en otro valor de la misma estructura de datos o que se puede transformar en la siguiente estructura de datos. Esto debe sonar como Tubos y Filtros en algún grado.
Dado esto, que llamo una operación que lleva unos estructuras de datos y construye un valor de la misma estructura de datos una transformación, mientras llamo una operación que lleva una estructura de datos y produce una diferente estructura de datos de seguimiento una derivación. El último paso de derivar un código que contiene la cadena se denomina emisor. (Por lo tanto, en general, el CodeGenerator toma la estructura de entrada y transforma, transforma, se deriva, se transforma, se deriva y finalmente emite).

Creo que enfatizar estos términos será beneficiosa en las comunicaciones, porque entonces es fácil hablar de cosas. Si escuchas "transformación", ya sabes "Ok, yo sólo necesito pensar en estas dos estructuras de datos", si escucha "emisor", ya sabes "Ok, yo sólo necesito saber esta estructura de datos y el idioma de destino.".

Sin embargo, ¿por dónde documentar estos patrones? La corriente de base de código se utiliza visitantes y ofrece clases denominadas como ValidatorTransformationBase (o InputStructureTransformationBase , etc., y así sucesivamente).

realmente no quiero añadir la definición de tales términos a las interfaces, porque en ese caso, tendría que repetir a mí mismo en todos y cada interfaz, lo que viola claramente SECO.

Estoy considerando hacer hincapié en la distinción entre las transformaciones y las derivaciones mediante la adición de nuevas interfases (que tendría que pensar en un nombre mejor para los TransformationBase-clases, pero entonces yo podría hacer piensa como ValidatorTransformation extiende ValidatorTransformationBase , o ValidatorDerivationFromInputStructure se extiende InputStructureTransformation ).

También creo que debería añadir una página personalizada a la documentación doxygen ya existente, como en "Glosario" o "Principios de Arquitectura", que contiene dichos principios. La única desventaja de esto sería que un contribuyente tendrá que encontrar esta página con el fin de aprender acerca de esta realidad.

Me estoy perdiendo posibilidades o estoy juzgando algo mal aquí, en su opinión?

- Saludos, Tetha

Answer 1

he visto algún barco software de código abierto con README-desarrolladores , un readme para los desarrolladores que listas, amongs otras, cosas tales como glosarios, RCS, direcciones URL de los wikis y así sucesivamente.

Answer 2

Se puede pegarlas en un href="http://java.sun.com/j2se/javadoc/writingdoccomments/#packagecomments" rel="nofollow noreferrer"> package.html archivo dentro del paquete, donde esas interfaces se definen. Usted puede ir tan lejos de la jerarquía de paquetes que tiene sentido.