Javaプログラムの高レベルの構造を文書化する方法は？
背景：共同編集者と私は学術雑誌の記事を書いています。研究の過程で、Javaでシミュレーションプログラムを作成しました。シミュレーションプログラムを他のユーザーが自由に利用できるようにしたいと考えています。 GitHubリポジトリでコードをホストすることにしました。他のユーザーが簡単に使用できるようにするために、プログラムに関する次のような適切なドキュメントを作成します。
- 各クラスおよびメソッドのJavadoc
- コードの使い方
- コードの高レベルな構造の説明
私の高レベルの質問は次のとおりです：プログラムの高レベルの構造を説明するために使用できる単語と図の良い例を提供できますか？これにはサブ質問が含まれます：
- どのクラスがどのパッケージに含まれているかをどのように示すのですか？
- どのパッケージが他のパッケージに依存しているかをどのように示すのですか？
- プログラム内のオブジェクト/クラスがどのように連携するかをどのように示すのですか？
- 私たちは、コードの設計で domain-driven design の原則を使用しようとしました。ドメイン内のオブジェクトとこれらのオブジェクトをエンコードする特定のソースコードファイルとの間の対応をどのように表示しますか？ （下記のプロジェクトの私の「ユビキタス言語」の説明を参照してください。）
これまでに行ったこと
ユビキタス言語
コードの「ユビキタス言語」の記述をファイルubiquitous-language.md、以下の内容。
このプロジェクトの目的は、さまざまなリードタイムモデル、レポートの遅延、および需要モデルの下で、単一の施設を備えた単純なサプライチェーンで補充ポリシーがどの程度うまく機能するかを調査することです。
各期間で、次のイベントが発生します。
- shipmentが現在の期間にfacilityに到着するようにスケジュールされている場合の場合、施設の在庫レベルはX単位で増加します。
- scheduleが現在の期間がレポート期間であることを示している場合、facilityレポートをsupplierに送信します。 supplierは、reportを瞬時に、または数遅延して受信する場合がありますscheduleで指定された週。
- supplierがreportを受け取った場合、補充方針、それはXユニットの補充量を計算します。製品のXユニットのshipmentは、l期間のリードタイム後に到着するようにスケジュールされます。
- 顧客は施設に到着し、製品のXユニットを要求します。満たされていない需要は失われます。
ソースコードの構造
コードの不完全な「高レベル」記述をファイルに入れますstructure.md、以下の内容。
パッケージレベルの構造
最高レベルでは、ソースコードは3つのパッケージに編成されています
com.gly.sfsmainメソッドを持つメインクラスは、このパッケージにあります。com.gly.sfs.modelドメインモデルクラスはこのパッケージにあります。com.gly.sfs.utilヘルパークラスはこのパッケージにあります。
通常、あなたはあなたが説明する目的のためにUMLを使います。 UMLは基本的に、構造と動作の2種類の図に分類されます。
構造図には、構成、配置、パッケージ、クラス、オブジェクト、およびコンポーネントが含まれます。 Behavioral図には、シーケンス、ステートマシン、通信、ユースケース、アクティビティ、および相互作用の概要が含まれます。
伝えようとしていることに応じて、伝えようとしているものを最もよく表すこれらの図をいくつか選び、そうすることで、会話で「レベルを上げる」ことができます。メソッド、パラメーター、コードについて説明するのではなく、一連の相互作用、静的クラスの依存関係、または作成することを選択した図について説明します。
シーケンス図（動作図の1つ）の例を添付しました。シーケンス図はデザインアーティファクトプロセスの真ん中にあるので、個人的には気に入っています。ほぼ同じ数の図が、入力として期待されるとおりに依存しています。いずれにしても、入力ダイアグラムは通常「理解」されているか、シーケンス図がすでに存在していることがわかります。ただし、静的クラス図とシーケンス図の両方を実行する場合があります（1つは構造図、もう1つは動作図）。
http://omarfrancisco.com/wp-content/uploads/2011/07/sequencediagram.png
私はこれまでにこの図を見たことがありませんが、このシステムについて多くのことがわかります。 4つの主要コンポーネント（システムの名詞-通常はクラス）があります。ビュー、コントローラー、データプロキシ、データプロバイダーです。矢印は「動作」またはメソッド呼び出しです。シーケンス図は基本的に、一連のコンポーネント間の1つの重要な相互作用を示すのに適しています。システムの重要なフローごとに1つのシーケンス図があります。この特定の図から、「コントローラー」が「phoneIsComplete（）」と呼ばれるメソッドを公開していることがわかります。
さて、あなたはうめき声を上げて、「アグ...これはシステムの全体像を与えません-それはシステムを介した個々の相互作用です」と考えるかもしれません。システムの洗練度によっては、それが有効な懸念事項になる可能性があります（単純なシステムは、シーケンス図のコレクションだけで間違いなくうまくいく可能性があります）。そこで、構造図に移り、静的クラス図のようなものを見てみましょう。
http://www.f5systems.in/apnashoppe/education//img/chapters/uml_class_diagram.jpg
クラス図は、カーディナリティとクラスの関係タイプという2つの重要なことを理解するのに役立ちます。クラスは、関連、集約、構成などのさまざまな方法で相互に関連付けることができます。技術的には、「静的なクラスの関係」と「インスタンスの関係」には違いがあります。ただし、実際にはこれらの線がぼやけています。主な違いは、静的クラスの関係には通常、カーディナリティが含まれないことです。上記の例を見て、何が見えるか見てみましょう。まず、「特別注文」と「通常注文」が「注文」（継承）のサブタイプであることがわかります。また、1つの顧客がN注文（「通常の注文」、「注文」、または「特別注文」の場合があります）を持っていることもわかります-Customerオブジェクトは実際には知りません。また、いくつかのメソッド（各クラスボックスの下半分）とプロパティ（各クラスボックスの上半分）も確認できます。
私は長い間UMLダイアグラムについて話し続けることができましたが、これは基本です。うまくいけば、それが役立ちます。
TLDR;行動と構造のUMLダイアグラムを1つ選び、その作成方法を学習すれば、達成しようとしていることを達成できます。
プログラムの高レベルの構造がどのように機能するか、クラスがどのようにうまく機能するかなどを説明するのが難しい場合は、次の格言を検討してください。
A picture is worth a thousand words.
コードについて絵を描く方法は、コード例を提供することです。それらの多く。これは、新しい顧客（コード）を作成する方法です。これが注文（コード）の処理方法です。これは、コードの利用者に開始場所を提供するだけでなく、すべてのオブジェクトがどのように接続され、相互作用するかを示します。私があなたのコードを使用している場合、あなたが私にできる最大の利点は、たくさんのコードサンプルを提供することです。
エンドユーザーのために絵を描く方法は、スクリーンショットを提供することです。それらの多く。このタスクを実行する場合は、これが最初に実行すること、これが次に実行することなどを示すスクリーンショットの後のスクリーンショット。
UMLは、ソフトウェアを作成する前にモデル化するためによく使用されますが、役立つ場合があります。ユースケース、クラスの相互作用などを示すいくつかの異なる図があります。詳細は here を参照してください。
https://www.websequencediagrams.com/ は、アプリケーション内のコンポーネント間、または分散アプリケーションのサービス間の相互作用を説明するための非常に便利なツールです。 UMLシーケンス図の作成と保守のプロセスがはるかに簡単になります。
良い点は、各ライフラインをアプリケーションのインターフェイスまたはクラス（通常は大きなプレーヤーをモデル化しているだけ）と考えると、そのクラスに流れ込む各ラインは、サポートする必要があるメソッドを表します。
さらに、イメージを取得するためのいくつかのダウンロードオプションがあります。図をwikiに埋め込む簡単な方法もいくつかあります。したがって、システム内のコンポーネントまたはサービス間の相互作用を説明するだけでなく、それをチームと通信するための優れた通信ツールです。