背景： 私の共同研究者と私は学術雑誌の記事を書いています。研究の過程で、Javaでシミュレーションプログラムを作成しました。シミュレーションプログラムを他の人が自由に利用できるようにしたいと考えています。GitHubリポジトリでコードをホストすることにしました。他の人が簡単に使用できるようにするために、次のような優れたドキュメントを作成します。

• 各クラスとメソッドのJavadoc
• コードの使用方法
• コードの高レベルの構造を記述する

私の高レベルの質問は次のとおり です。プログラムの高レベルの構造を説明するために使用できる単語と図の良い例を提供できますか？ これにはサブ質問として含まれます：

1. どのパッケージにどのクラスが含まれているかをどのように示しますか？
2. 他のパッケージに依存するパッケージをどのように表示しますか？
3. プログラム内のオブジェクト/クラスがどのように連携するかをどのように示しますか？
4. 私たちは、コードの設計にドメイン駆動設計原則を使用しようとしました。ドメイン内のオブジェクトと、これらのオブジェクトをエンコードする特定のソースコードファイルとの対応をどのように示しますか？（以下のプロジェクトの私の「ユビキタス言語」の説明を参照してください。）

これまでにやったこと

ユビキタス言語

コードの「ユビキタス言語」の説明をファイルのubiquitous-language.md次の内容に入れます。

このプロジェクトの目的は、異なるリードタイムモデル、レポート遅延、および需要モデルの下で、単一施設を備えた単純なサプライチェーンで補充ポリシーがどの程度うまく機能するかを調査することです。

各期間で、次のイベントが発生します。

1. 出荷が現在の期間に施設に到着するようにスケジュールされている場合、施設の在庫レベルはX単位だけ増加します。
2. 現在の期間がレポート期間であることがスケジュールに示されている場合、施設はレポートをサプライヤーに提出し ます。サプライヤーは、受信することができるレポート によって指定されるように、数週間の遅れまたは、瞬時スケジュール。
3. サプライヤがレポートを受信した場合、補充ポリシーに基づいて、 Xユニットの補充量を計算します。出荷製品のXユニットは、L期間のリードタイムの後に到着する予定であろう。
4. 顧客は施設に到着し、製品のXユニットを要求します。満たされていない需要は失われます。

ソースコード構造

コードの不完全な「高レベル」説明をファイルstructure.mdに入れます。内容は以下のとおりです。

パッケージレベルの構造

最高レベルでは、ソースコードは3つのパッケージに編成されています。

• com.gly.sfsmainメソッドを 持つメインクラスはこのパッケージにあります。
• com.gly.sfs.model ドメインモデルクラスはこのパッケージにあります。
• com.gly.sfs.util ヘルパークラスはこのパッケージにあります。

通常、説明する目的でUMLを使用します。UMLは基本的に、構造図と動作図の2種類の図に分類されます。

構造図には、構成、展開、パッケージ、クラス、オブジェクト、およびコンポーネントが含まれます。 動作図には、シーケンス、ステートマシン、通信、ユースケース、アクティビティ、および相互作用の概要が含まれます。

あなたが伝えようとしているものに応じて、あなたが伝えようとしているものを最もよく表すこれらの図のいくつかを選び、そうすることで会話を「レベルを上げる」ことができます。メソッド、パラメーター、コードについて話す代わりに、相互作用のシーケンス、静的クラスの依存関係、または作成することを選択した図について話します。

シーケンス図の例（動作図の1つ）を添付しました。シーケンス図は、設計成果物プロセスの真ん中にあるので、個人的には好きです-入力として期待されるように、ほぼ同数の図がそれに依存します。とにかく、入力ダイアグラムは通常、とにかく「理解」されているか、シーケンス図がすでに存在していることを暗示しています。ただし、静的クラス図とシーケンス図（1つの構造図と1つの動作図）の両方を実行することがあります。

http://omarfrancisco.com/wp-content/uploads/2011/07/sequencediagram.png

私の人生でこの図を見たことがありませんが、このシステムについて多くのことを伝えることができます。4つの主要なコンポーネント（システムの名詞-通常はクラス）があります：ビュー、コントローラー、データプロキシ、およびデータプロバイダー。矢印は「動作」またはメソッド呼び出しです。基本的にシーケンス図は、多数のコンポーネント間の単一の重要な相互作用を示すのに適しています。システムの重要なフローごとに1つのシーケンス図があります。この特定の図から、「Controller」が「phoneIsComplete（）」というメソッドを公開していることがわかります。このメソッドは、DataProviderProxyの「lookupPhone（）」メソッドに依存し、DataProviderProxyの「lookupPhone（）」メソッドに依存します。

今、あなたはうめき声を上げ、「ugg ...これはシステムの全体像を与えてくれません。それは単にシステムを介した個々の相互作用です」と思うかもしれません。システムの洗練度によっては、それが有効な懸念事項になる可能性があります（単純なシステムは、シーケンス図のコレクションだけで間違いなく対処できます）。そのため、構造図に移り、静的クラス図のようなものを見ます。

http://www.f5systems.in/apnashoppe/education//img/chapters/uml_class_diagram.jpg

クラス図は、カーディナリティとクラスリレーションシップタイプという2つの重要なことを理解するのに役立ちます。クラスは、関連付け、集約、構成など、さまざまな方法で互いに関連付けることができます。技術的に言えば、「静的クラスの関係」と「インスタンスの関係」には違いがあります。ただし、実際にはこれらの線はぼやけています。主な違いは、静的クラスの関係には通常カーディナリティが含まれないことです。上記の例を見て、何が見えるか見てみましょう。まず、「特別注文」と「通常注文」が「注文」（継承）のサブタイプであることがわかります。また、1人の顧客がN個の注文（「通常注文」、「注文」、または「特別注文」）を持っていることがわかります-Customerオブジェクトは 本当に知っている。また、いくつかのメソッド（各クラスボックスの下半分）とプロパティ（各クラスボックスの上半分）を確認できます。

私は長い間UML図について話し続けることができましたが、これが基本です。うまくいけばそれが助けになる。

TLDR; 1つの動作UMLダイアグラムと1つの構造UMLダイアグラムを選択し、作成方法を学習すると、達成しようとしていることを達成できます。

プログラムの高レベルの構造がどのように機能するか、クラスがどのように連携するかなどの説明が困難な場合は、次の格言を考慮してください。

A picture is worth a thousand words.

コードに関する図を描く方法は、コード例を提供することです。 それらの多く。これは、新しい顧客（コード）を作成する方法です。これが注文（コード）の処理方法です。これは、コードのコンシューマーに開始点を提供するだけでなく、すべてのオブジェクトがどのように相互に接続して相互作用するかを示しています。私があなたのコードを使用していた場合、あなたが私にできる最大の恩恵は、多くのコードサンプルを提供することです。

エンドユーザーに絵を描く方法は、スクリーンショットを提供することです。 それらの多く。このタスクを実行する場合、これが最初に行うこと、これが次に行うことなどを示す、スクリーンショットの後のスクリーンショット

UMLは、作成される前にソフトウェアをモデル化するためによく使用されますが、有用な場合があります。ユースケース、クラスの相互作用などを示すいくつかの異なる図があります。詳細については、こちらをご覧ください。

https://www.websequencediagrams.com/は、アプリケーション内のコンポーネント間、または分散アプリケーション内のサービス間の相互作用を記述するための非常に便利なツールであることがわかりました。UMLシーケンス図の作成と保守のプロセスがはるかに簡単になります。

良い点は、各ライフラインをアプリケーションのインターフェイスまたはクラスと見なす場合（通常、大きなプレーヤーをモデル化するだけです）、そのクラスに流れる各行は、サポートする必要があるメソッドを表します。

さらに、画像を取得するためのダウンロードオプションがいくつかあります。Wikiに図を埋め込む簡単な方法もいくつかあります。したがって、システム内のコンポーネントまたはサービス間の相互作用を記述し、それをチームと通信することは素晴らしいコミュニケーションツールです。