ドキュメントの重要な用語とパターンの用語集をどこに置くべきですか？ [閉まっている

Question

ご挨拶。

一貫した用語を構築するために、コードに特定のパターンを文書化したい（ソフトウェアに関するコミュニケーションを緩和するため）。ただし、指定された用語を定義する場所はわかりません。同じレベルに到達するために、例：

コードジェネレーターがあります。このコードジェネレーターは、パーサーから特定の入力構造を受け取ります（はい、入力構造という名前は理想よりも少ないかもしれません）。この入力構造は、さまざまな後続のデータストラクチャに変換されます（検証プロセスの抽象的な説明など）。これらの各データストラクチャは、同じデータストラクチャの別の値に変換されるか、次のデータストラクチャに変換できます。これは、ある程度パイプとフィルターのように聞こえるはずです。
これを考慮して、データストラクチャを取得し、同じデータストラクチャの値を構築する操作を変換と呼びますが、データストラクチャを取得し、異なるフォローアップデータストラクチャを作成する操作を呼び出します。コードを含む文字列を導出する最後のステップは、エミッティングと呼ばれます。 （したがって、全体として、コードゲネレーターは入力構造を取り、変換、変換、派生、変換、導出、最終的に放出します）。

これらの用語を強調することは、コミュニケーションにおいて有益であると思います。なぜなら、物事について話すのは簡単だからです。 「変換」が聞こえた場合、「OK、これら2つのデータストラクチャについて考える必要があります」、「エミッティング」が聞こえる場合は、「OK、このデータストラクチャとターゲット言語を知る必要があります。」

しかし、これらのパターンはどこで文書化しますか？現在のコードベースは訪問者を使用し、like validatortransformationbaseと呼ばれるクラスを提供しますu003CResultType>（またはinputStructureTransFormationBaseu003CResultType> 、そしてそのようなことなど）。

そのような用語の定義をインターフェイスに追加したくありません。その場合、明らかに乾燥しているすべてのインターフェイスで自分自身を繰り返さなければならないからです。

さらにインターフェイスを追加することにより、変換と導出の区別を強調することを検討しています（変換ベースクラスのより良い名前について考える必要がありますが、ValidatorTransformationのような拡張validatorTransformationBaseのようなものができると考えています。u003CValidator> 、またはvalibatorderivation frominputStructureは、入力構造トランス形成を拡張しますu003CValidator>）。

また、そのような原則を含む「用語集」または「アーキテクチャの原則」のように、すでに存在するDoxygenドキュメントにカスタムページを追加する必要があると思います。これの唯一の欠点は、実際にこれについて学ぶために、貢献者がこのページを見つける必要があることです。

私はあなたの意見でここで何か間違ったものを判断している可能性がありませんか、それとも私はここで何か間違っていますか？

- よろしく、テタ

Answer 1

オープンソースのソフトウェア船をいくつか見てきました readme-developers, 、用語集、RCS、WIKIのURLなどをリストアップする開発者向けのREADME。

Answer 2

あなたはそれらをaに貼り付けることができます package.html これらのインターフェイスが定義されているパッケージ内のファイル。理にかなっている限り、パッケージの階層を上げることができます。