Salutations.Où placer un glossaire de termes et de motifs importants dans la documentation?
Je souhaite documenter certains motifs dans le code afin de construire une terminologie cohérente (afin d'améliorer la communication sur le logiciel). Je ne suis cependant pas sûr de savoir où définir les termes donnés. Pour obtenir le même niveau, un exemple:
J'ai un générateur de code. Ce générateur de code reçoit une certaine InputStructure de l'analyseur (oui, le nom InputStructure peut être moins qu'idéale). Cette InputStructure est ensuite transformée en diverses structures de données ultérieures (comme une description abstraite du processus de validation). Chacune de ces structures de données peut être soit transformée en une autre valeur de la même structure de données, soit transformée en la structure de données suivante. Cela devrait ressembler à des tuyaux et des filtres dans une certaine mesure. Pour cette raison, j'appelle une opération qui prend une structure de données et construit une valeur de la même structure de données une transformation, tandis que j'appelle une opération qui prend une structure de données et produit une structure de données de suivi différente une dérivation. L'étape finale de dérivation d'une chaîne contenant du code est appelée émission. (Ainsi, globalement, le codegenerator prend la structure d'entrée et transforme, transforme, dérive, transforme, dérive et finalement émet). Je pense que mettre l'accent sur ces termes sera bénéfique dans les communications, car alors il est facile de parler de choses. Si vous entendez "transformation", vous savez "Ok, je n'ai besoin de penser qu'à ces deux structures de données", si vous entendez "émettre", vous savez "Ok, je n'ai besoin que de connaître cette infrastructure de données et la langue cible".
Cependant, où puis-je documenter ces modèles? La base de code actuelle utilise des visiteurs et offre des classes appelées ValidatorTransformationBase <ResultType> (ou InputStructureTransformationBase <ResultType>, et ainsi de suite). Je ne veux pas vraiment ajouter la définition de tels termes aux interfaces, parce que dans ce cas, je devrais me répéter sur chaque interface, ce qui viole clairement DRY.
J'envisage de mettre l'accent sur la distinction entre les transformations et Dérivations en ajoutant d'autres interfaces (je dois penser à un meilleur nom pour les TransformationBase classes, mais je pourrais faire pense comme extends ValidatorTransformation ValidatorTransformationBase <Validator>, ou ValidatorDerivationFromInputStructure extends InputStructureTransformation <Validator>).
Je pense aussi que je devrais ajouter une page personnalisée à la documentation doxygen déjà existante, comme dans "Glossaire" ou "principes d'architecture", qui contient de tels principes. Le seul inconvénient de ceci serait qu'un contributeur devra trouver cette page afin d'apprendre réellement à ce sujet.
Ai-je manqué des possibilités ou est-ce que je juge quelque chose de mal ici à votre avis?
- Cordialement, Tetha