Dove mettere un glossario dei termini e modelli importanti nella documentazione? [chiuso]

Question

Saluti.

voglio documentare alcuni modelli nel codice al fine di costruire una terminologia coerente (al fine di comunicazione easen sul software). Sono, comunque, incerto, in cui definire i termini indicati. Al fine di ottenere allo stesso livello, un esempio:

Ho un generatore di codice. Questo generatore di codice riceve un certo InputStructure dal parser (sì, il nome InputStructure potrebbe essere meno che ideale). Questo InputStructure viene poi trasformato in varie strutture di dati successivi (come una descrizione astratta del processo di convalida). Ciascuna di queste strutture di dati possono essere sia trasformato in un altro valore della stessa datastructure oppure può essere trasformato nella successiva datastructure. Questo dovrebbe suonare come tubi e filtri in una certa misura.
Dato questo, invito operazione che richiede Datastructures e costruisce un valore dello stesso datastructure una trasformazione, mentre chiamo un'operazione che richiede un datastructure e produce un diverso follow-up datastructure una derivazione. La fase finale di derivare un codice contenente stringa è chiamato emettitori. (Quindi, nel complesso, il CodeGenerator prende l'input-struttura e trasforma, trasforma, deriva, trasformazioni, deriva e infine emette).

Credo che insisto questi termini sarà benefitial nelle comunicazioni, perché allora è facile parlare di cose. Se si sente "trasformazione", lo sai "Ok, ho solo bisogno di pensare a queste due strutture di dati", se si sente "che emette", lo sai "Ok, ho solo bisogno di sapere questo datastructure e la lingua di destinazione.".

Tuttavia, se posso documentare questi modelli? La corrente di base di codice utilizza i visitatori e offre corsi chiamati come ValidatorTransformationBase (o InputStructureTransformationBase , e così uno e così via).

Non voglio davvero aggiungere alla definizione di tali termini alle interfacce, perché in quel caso, avrei dovuto ripetermi su ogni interfaccia, che viola ben asciutto.

sto valutando l'opportunità di sottolineare la distinzione tra Trasformazioni e derivazioni con l'aggiunta di ulteriori interfacce (avrei dovuto pensare a un nome migliore per i TransformationBase-classi, ma poi ho potuto fare pensa come ValidatorTransformation estende ValidatorTransformationBase , o ValidatorDerivationFromInputStructure si estende InputStructureTransformation ).

Penso anche che dovrei aggiungere una pagina personalizzata per la documentazione Doxygen già esistenti, come in "Glossario" o "architettura Principi", che contiene tali principi. L'unico svantaggio di questo sarebbe che un collaboratore avrà bisogno di trovare questa pagina al fine di realmente imparare su questo.

Mi sto perdendo possibilità o sto a giudicare qualcosa che non va qui, nella tua opinione?

- Saluti, Tetha

Answer 1

ho visto qualche nave software Open source con README-sviluppatori , un readme per gli sviluppatori che elenchi, amongs altri, cose come glossari, RCS, gli URL per i wiki e così via.

Answer 2

Si potrebbe attaccarli in un href="http://java.sun.com/j2se/javadoc/writingdoccomments/#packagecomments" rel="nofollow noreferrer"> file di package.html all'interno della confezione in cui tali interfacce sono definite. Si può andare il più in alto nella gerarchia pacchetto come un senso.