背景： 我和我的合作者正在为学术期刊撰写文章。在研究过程中，我们用Java编写了一个仿真程序。我们想让仿真程序免费供其他人使用。我们已决定将代码托管在GitHub存储库上。为了使其他人易于使用，我们希望为程序编写良好的文档，包括：

• 每个类和方法的Javadocs
• 如何使用代码
• 描述代码的高级结构

我的高级问题是： 您能否提供一个可以用来描述程序高级结构的单词和图表的好例子？ 这包括作为子问题：

1. 我们如何显示哪些包中包含哪些类？
2. 我们如何显示哪些软件包依赖于其他软件包？
3. 我们如何显示程序中的对象/类如何协同工作？
4. 我们已尝试在代码设计中使用领域驱动的设计原则。我们如何显示域中的对象与编码这些对象的特定源代码文件之间的对应关系？（请参阅下面我对项目的“通用语言”说明。）

到目前为止我做了什么

无处不在的语言

我们将代码的“普遍语言”描述放在文件中ubiquitous-language.md，内容如下。

该项目的目的是研究在不同的提前期模型，报告延迟和需求模型下，补货策略在具有单个设施的简单供应链中的执行情况。

在每个期间，发生以下事件：

1. 如果计划在当前期间将货物运送到工厂，则工厂的库存水平将增加X单位。
2. 如果计划表指示当前期间为报告期，则工厂将向 供应商提交报告。该供应商可能会收到报告 瞬间，或者几个星期的延迟，由指定的时间表。
3. 如果供应商已收到报告，则根据 补货策略，它将计算X单位的补货数量。一个出货的产品的X单位将被安排升周期的筹备时间之后抵达。
4. 客户到达工厂并需要X单位的产品。任何未满足的需求都会丢失。

源代码结构

我们在structure.md下面的文件中放置了不完整的代码“高级”描述。

包装等级结构

在最高级别，源代码分为三个包

• com.gly.sfs 该main方法的主类位于此程序包中。
• com.gly.sfs.model 域模型类驻留在此程序包中。
• com.gly.sfs.util 帮助程序类驻留在此程序包中。

通常，您会出于描述的目的使用UML。UML基本上分为两种类型的图：结构图和行为图。

结构图包括：组成，部署，程序包，类，对象和组件。 行为图包括：序列，状态机，通信，用例，活动和交互概述。

根据您要传达的内容，您可以选择一些最能代表您想要传达的内容的图表，从而使对话“更上一层楼”。您不是在谈论方法，参数和代码，而是在谈论交互顺序，静态类依赖关系或选择创建的任何图表。

我已经附上了一个时序图的示例（行为图之一）。我个人喜欢序列图，因为它就在设计工件过程的中间-大致相等数量的图依赖于它所期望的输入。我发现输入图通常无论如何都是“理解”的，或者顺序图已经暗示了它们的存在。但是，有时我同时做静态类图和顺序图（一个结构图和一个行为图）。

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

我一生中从未见过该图，但是我可以说一些有关此系统的信息。有四个主要组件（系统中的名词-通常是类）：视图，控制器，数据代理和数据提供程序。箭头是“行为”或方法调用。顺序图基本上有利于显示一堆组件之间的单个重要交互。对于通过系统的每个重要流程，您都有一个时序图。我可以从此特定图中看出，“ Controller”公开了一个名为“ phoneIsComplete（）”的方法，该方法又取决于DataProviderProxy的“ lookupPhone（）”方法，而该方法又取决于DataProvider的“ lookupPhone（）”方法。

现在，您可能会gro吟，然后想：“哎呀……这并不能使我对系统有个全面了解-只是通过系统的个人交互”。取决于系统的复杂程度，这可能是一个有效的问题（简单的系统肯定可以仅通过一系列时序图来实现）。因此，我们转到结构图，然后看一看类似静态类图的内容：

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

类图可以帮助我们弄清楚两个重要的事情：基数和类关系类型。类可以通过不同的方式相互关联：关联，聚合和组合。从技术上讲，“静态类关系”和“实例关系”之间是有区别的。但是，实际上您会看到这些线条模糊。主要区别在于静态类关系通常不包括基数。让我们看一下上面的例子，看看我们能看到什么。首先，我们可以看到“特殊订单”和“普通订单”是“订单”（继承）的子类型。我们还可以看到一个客户有N个订单（可以是“普通订单”，“订单”或“特殊订单”）-客户对象没有 真的不知道。我们还可以看到许多方法（在每个类框的下半部分）和属性（在每个类框的上半部分）。

我可以长时间谈论UML图，但这是基础。希望有帮助。

TLDR；选择一个行为和一个结构化的UML图，学习如何创建它，然后您将完成想要完成的工作。

如果您在描述程序高级结构的工作方式以及类如何协同工作等方面遇到困难时，请考虑以下原则：

A picture is worth a thousand words.

绘制有关代码的图片的方式是提供代码示例。 其中很多。这是创建新客户（代码）的方式。这是您处理订单（代码）的方式。这不仅为您的代码使用者提供了一个起点，而且还说明了所有对象如何连接在一起并进行交互。如果我使用的是您的代码，那么您可以帮我的最大忙就是提供很多代码示例。

为最终用户绘制图片的方式是提供屏幕截图。 其中很多。屏幕截图后的屏幕截图说明了如果您想执行此任务，这是您首先要做的，这是您下一步要做的，依此类推。

UML通常用于在软件创建之前对其进行建模，但它可能会很有用。有几个不同的图来说明用例，类交互等。您可以在此处了解更多信息。

我发现 https://www.websequencediagrams.com/是一个非常有用的工具，用于描述应用程序中组件之间或分布式应用程序中服务之间的交互。它只是使创建和维护UML序列图的过程变得更加容易。

令人高兴的是，如果您将每条生命线视为应用程序中的接口或类（我通常只是对大型参与者进行建模），那么流入该类的每一行都代表了您必须支持的方法。

此外，还有一些下载选项来获取图像。还有一些简单的方法可以将图表嵌入Wiki。因此，它是描述系统中组件或服务之间的交互以及与团队进行沟通的一个很好的交流工具。