Background: My collaborators and I are writing an article for an academic journal. In the course of our research, we wrote a simulation program in Java. We want to make the simulation program freely available for others to use. We have decided on hosting the code on a GitHub repository. In order to make it easy for others to use, we want to write good documentation for our program, including:
- Javadocs for each class and method
- How to use the code
- Describing the high-level structure of the code
My high-level question is: Could you provide a good example of the words and diagrams that can be used to describe the high-level structure of a program? This includes as sub-questions:
- How do we show what classes are contained in which packages?
- How do we show what packages depend on other packages?
- How do we show how the objects/classes in the program work together?
- We have tried to use domain-driven design principles in the design of my code. How do we show the correspondence between the objects in the domain and the particular source code files encoding these objects? (See my "ubiquitous language" description of the project below.)
What I have done so far
We put a "ubiquitous language" description of the code
in a file
The purpose of this project is to study how well a replenishment policy performs in a simple supply chain with a single facility, under different lead time models, report delays and demand models.
In each period, the following events occur:
- If a shipment is scheduled to arrive at the facility at the current period, then the inventory level of the facility is incremented by X units.
- If the schedule indicates that the current period is a reporting period, then the facility submits a report to the supplier. The supplier may receive the report instantaneously, or with a delay of several weeks, as specified by the schedule.
- If the supplier has received a report, then based on the replenishment policy, it will calculate a replenishment quantity of X units. A shipment of X units of the product will be scheduled to arrive after a lead time of l periods.
- Customers arrive at the facility and demand X units of the product. Any unmet demand is lost.
Source Code Structure
We put an incomplete "high-level" description of the code
in a file
Package Level Structure
At the highest level, the source code is organized into three packages
com.gly.sfsThe main class with the
mainmethod resides in this package.
com.gly.sfs.modelThe domain model classes reside in this package.
com.gly.sfs.utilHelper classes reside in this package.