Wo ein Glossar wichtiger Begriffe und Muster in der Dokumentation setzen? [geschlossen]

Question

Grüße.

Ich möchte bestimmte Muster im Code, um dokumentieren, eine konsistente Terminologie (um easen Kommunikation über die Software) aufzubauen. Ich bin jedoch nicht sicher, wo die Bedingungen zu definieren, gegeben. Um auf dem gleichen Niveau zu erhalten, ein Beispiel:

ich einen Code-Generator haben. Dieser Code-Generator erhält eine bestimmte InputStructure vom Parser (ja, könnte der Name InputStructure weniger als ideal). Diese InputStructure werden dann in verschiedene nachfolgende Datenstrukturen (wie eine abstrakte Beschreibung des Validierungsprozesses) transformieren. Jede dieser Datenstrukturen kann entweder in einer anderen Wert der gleichen Datenstruktur umgewandelt werden oder es kann in die nächste Datenstruktur umgewandelt werden. Dies sollte klingen wie Rohre und Filter bis zu einem gewissen Grad.
Vor diesem Hintergrund habe ich eine Operation aufrufen, die ein Datenstrukturen nimmt und konstruiert einen Wert von der gleichen Datenstruktur eine Transformation, während ich eine Operation nennen, die eine Datenstruktur nimmt und eine andere Follow-up-Datenstruktur eine Ableitung. Der letzte Schritt der Code einen String mit Herleiten aussendet genannt. (Also, insgesamt nimmt der Codegenerator die Input-Struktur und Transformationen, Transformationen, herleitet, Transformationen, herleitet und schließlich aussendet).

Ich denke, betonen diese Begriffe werden in der Kommunikation benefitial sein, denn dann ist es leicht zu reden über die Dinge. Wenn Sie „Transformation“ hören, wissen Sie „Ok, ich nur über diese beiden Datenstrukturen denken müssen“, wenn Sie hören „Austritts“, wissen Sie „Ok, ich habe nur diese Datenstruktur müssen wissen, und die Zielsprache.“.

Wo jedoch dokumentieren ich diese Muster? Die aktuellen Codebasis Einsatz Besucher und bietet Klassen genannt wie ValidatorTransformationBase (oder InputStructureTransformationBase , und so ein und so weiter).

Ich will nicht wirklich die Definition dieser Begriffe auf die Schnittstellen hinzuzufügen, denn in diesem Fall würde ich mich Schnittstelle auf jedem haben zu wiederholen, die DRY eindeutig verletzt.

Ich betrachte die Unterscheidung zwischen Transformationen und Ableitungen zu betonen durch weitere Schnittstellen hinzugefügt (ich würde für die TransformationBase-Klassen über einen besseren Namen denken, aber dann konnte ich tun, denkt wie ValidatorTransformation erweitert ValidatorTransformationBase oder ValidatorDerivationFromInputStructure erweitert InputStructureTransformation ).

Ich denke auch, sollte ich eine benutzerdefinierte Seite der doxygen Dokumentation hinzufügen bereits vorhandenen, wie in „Glossar“ oder „Architecture Principles“, die solche Prinzipien enthält. Der einzige Nachteil wäre, dass ein Beitrag diese Seite, um darüber zu lernen tatsächlich finden muß.

Am I Möglichkeiten fehlt, oder bin ich etwas falsch zu urteilen hier Ihrer Meinung nach?

- Regards, Tetha

Answer 1

Ich habe einige Open-Source-Software-Schiff gesehen mit Readme-Entwickler , eine Readme für Entwickler, dass die Listen, amongs andere Dinge wie Glossare, RCS, Urls für Wikis und so weiter.

Answer 2

Sie könnten kleben sie in einer package.html -Datei im Paket, in dem diese Schnittstellen definiert. Sie können so weit die Pakethierarchie wie macht Sinn gehen.