Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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:

  1. How do we show what classes are contained in which packages?
  2. How do we show what packages depend on other packages?
  3. How do we show how the objects/classes in the program work together?
  4. 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

Ubiquitous language

We put a "ubiquitous language" description of the code in a file ubiquitous-language.md, contents below.

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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 structure.md, contents below.

Package Level Structure

At the highest level, the source code is organized into three packages

  • com.gly.sfs The main class with the main method resides in this package.
  • com.gly.sfs.model The domain model classes reside in this package.
  • com.gly.sfs.util Helper classes reside in this package.
share|improve this question
1  
    
when you say "high-level structure of the code," do you just mean which classes are in which packages? You can do that by drawing a dotted line around the classes in your class diagram that belong to a specific package, and labeling the dotted line with the package name. It's easy enough to find examples of class diagrams. –  Robert Harvey Mar 25 at 19:10
    
Big props for releasing academic code. –  Felix Mar 26 at 13:29
    
@RobertHarvey See my edits to the question. Showing which classes are in which packages is more straightforward, showing how the classes work together is more tricky. –  I Like to Code Mar 26 at 23:58
1  
You might want to add package-level javadoc as well. –  haylem Mar 31 at 11:18

4 Answers 4

up vote 4 down vote accepted
+150

Normally, you'd use UML for the purpose you describe. UML basically breaks down into two types of diagrams: structural and behavioral.

Structural diagrams include: composition, deployment, package, class, object, and component. Behavioral diagrams include: sequence, state machine, communication, use case, activity, and interaction overview.

Depending on what you're trying to convey, you pick a few of these diagrams which best represent whatever you're trying to convey, and by so doing you allow the conversation to "move up a level". Instead of talking about methods, parameters, and code, you're talking about sequence of interactions, or static class dependencies, or whatever diagrams you choose to create.

I've attached an example of a sequence diagram (one of the behavior diagrams). I personally like the sequence diagram because it's right in the middle of the design artifact process -- roughly an equal number of diagrams depend on it as it expects as input. I find that the input diagrams are typically "understood" anyway, or the sequence diagram already implies their existence. However, sometimes I do both static class diagrams and sequence diagrams (one structural and one behavioral diagram).

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

I have never seen this diagram before in my life, but I can tell a number of things about this system. There are four major components (the nouns in your system -- typically the classes): View, Controller, Data Proxy, and Data Provider. The arrows are "behaviors" or method invocations. A sequence diagram is basically good for showing a single important interaction between a bunch of components. You have one sequence diagram for each important flow through your system. I can tell from this particular diagram that "Controller" exposes a method called "phoneIsComplete()", which in turn depends on DataProviderProxy's "lookupPhone()" method, which in turn depends on DataProvider's "lookupPhone()" method.

Now, you might groan and think "uggg... this doesn't give me a big picture of the system -- it's just individual interactions through the system". Depending on the sophistication of the system, that might be a valid concern (simple systems can definitely get by with just a collection of sequence diagrams). So, we move over to the structural diagrams and we look at something like a static class diagram:

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

Class diagrams help us figure out two important things: cardinality, and class relationship types. Classes can be related to one another in different ways: association, aggregation, and composition. Technically speaking, there's a difference between "static class relationships" and "instance relationships". However, in practice you see these lines blurred. The main difference is that static class relationships don't usually include cardinality. Let's look at the example above and see what we can see. First, we can see that "Special Order" and "Normal Order" are subtypes of "Orders" (inheritance). We can also see that one Customer has N Orders (which may be "Normal Orders", "Orders", or "Special Orders") -- the Customer object doesn't really know. We can also see a number of methods (in the bottom half of each class box) and properties (top half of each class box).

I could keep talking about UML diagrams for a long time, but this is the basics. Hopefully that helps.

TLDR; Pick one behavioral and one structural UML diagram, learn how to create it, and you'll accomplish what you're trying to accomplish.

share|improve this answer
    
Hey, thanks for the bounty! :-) –  Joe Rounceville Mar 31 at 19:15

If you're having difficulty describing things like how the high-level structure of your program works, and how the classes work well together, consider the following maxim:

A picture is worth a thousand words.

The way you paint a picture about code is to provide code examples. Lots of them. This is how you create a new customer (code). This is how you process an order (code). Not only does this give the consumer of your code a place to start, it illustrates how all of the objects connect together and interact. If I were using your code, the biggest favor you could do me is to provide lots of code samples.

The way you paint a picture for an end-user is to provide screenshots. Lots of them. Screenshot after screenshot that illustrates, if you want to do this task, this is what you do first, this is what you do next, etc.

share|improve this answer
    
+1, Code examples of common tasks is the first thing anyone trying to learn an API is going to want. Javadocs and some description of the relationship between classes will fill in the blanks, but are not sufficient. –  Doval Mar 20 at 18:47
5  
+1 for not mentioning UML. –  Doc Brown Mar 20 at 19:38
3  
@DocBrown UML is certainly not the tool for every job. However, if you're modeling something that fits the pattern of one of the UML diagrams (for example, modeling class relationships), then UML does offer a format which readers are likely to be familiar with, and familiarity eases readability. –  Mike Mar 25 at 21:41
    
@DocBrown Why would UML be a bad solution in this case? –  Onno Mar 27 at 13:16
    
@Onno: this was a little bit ironic of mine, but I think UML has only limited support for such a "high level" description, and a very unclear semantics. But I guess using package diagrams will be ok here (as long as the UML tool will allow to draw classes within packages). –  Doc Brown Mar 27 at 13:29

UML, while often used to model software before it is created, could be useful. There are several different diagrams that illustrate use-cases, class-interactions, etc. etc. You can see more about it here.

share|improve this answer

I find https://www.websequencediagrams.com/ an extremely useful tool for describing the interaction between components within an application, or between services in a distributed application. It just makes the process of creating and maintaining UML sequence diagrams much easier.

The nice thing is, if you consider each lifeline to be the interface or class in your application (I usually just model the big players), then each line flowing into that class represents a method that you must support.

Additionally, there are some download options to get the image. There are also some easy ways to embed the diagram in a wiki. So it's a great communication tool to describe the interaction between components or services in a system, as well as communicating that with the team.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.