This article was originally published on Medium.

The most used by me (and my favorite) UML diagram is Sequence Diagram. Implementation designs of each new feature I’m working on are loaded with Sequence diagrams. I mean it, totally chock-full.

In general, a Sequence diagram describes how and in what order objects in our system interact with each other, arranged in time sequence. In this article, I’m about to show you the notations of these interactions through “The Little Prince” narrator’s interactions with the world around him. Have you read Antoine de Saint-Exupéry’s novel?

I will summarise only the part that is relevant to the current article. It will be connected, I promise.

...

Okay, briefly, when he was a child, the Narrator read a book on jungles and was fascinated by the fact that a boa constructor swallows his prey whole and then sleeps for few months while digesting the meal. He drew a picture of the boa in this state.

Here is a boa roentgen, if you have any doubts.

When he showed it to adults, they all thought it was a lumpy hat and suggested he stop messing about and study the “important subjects” in school instead. The adults’ criticism killed the artist. The child grew up, became a pilot, and flew worldwide (not the worst). As an adult, he used the boa drawing to decide what topics to talk about with other adults. If an adult saw a lumpy hat, the Narrator spoke about golf and bridge and politics; he never mentioned jungles or boa constrictors or stars.

...

Now, back to the Sequence Diagram.

Sequence Diagram

In my opinion, a sequence diagram is best to represent cross-services end-to-end scenarios or specific flow (or part of it) within a particular service. I’m creating this diagram before I start to design implementation, just to understand the requirements. It’s a contract between me and other involved guys, such as product manager, software architect, team members, etc. These diagrams are the VIP guests of each feature-related meeting.

The sequence diagram depicts the objects involved in the scenario and the sequence of messages exchanged between them required to execute the functionality. It’s pretty cool and handy.

...

Let’s start with an overview of basic symbols:

Basic Symbols

The sequence diagram has only two basic symbols: object and focus of control.

Object

The Sequence diagram object is notated by a box with the name and dashed line extended down below. While the object can represent a specific class (depending on what kind of logic you describe), I mostly use it to define a microservice.

However, today, it will represent a Narrator.

The dashed line is also known as the timeline, shows the sequential events that occur to an object during the charted process. Note that time in a Sequence diagram is all about ordering. The timeline is not relevant for the duration of the interaction.

Focus of Control

The focus of control is the block that overlays the object’s timeline. This is the time in which the object is actually being utilized.

...

Now we are jumping to the exciting part — the interaction between objects!

Interactions

The objects in software systems can interact synchronously or asynchronously.

Synchronous Message

Synchronous messaging is when the caller makes a call, expecting that object that’s being called to do some processing and return control back to the caller at some point in time.

Back to our Narrator. Remember the bao drawing? He showed the drawing of bao to adults and actually waited to hear what they see:

The synchronous message is notated by a solid line with a filled-in and enclosed arrow, pointing from the caller (Narrator) to the callee (Adult). And you can see that it starts a new focus of control on the callee.

Once the call that was made completes, control is returned back to the caller. This is represented by the return line, which is a dashed line with an open arrow pointing to the caller.

If you describe the flow between classes, I mean, the Narrator is calling to the Adult’s method, you can place the method name on the line. It’s also possible to put the passed parameters (depend on the level of details you are looking for).

The return line can be identified with return values that are coming back to the caller. Again, according to the level of the details you decided on. It’s often common to not label the return line at all.

“Less is more” — Ludwig Mies van der Rohe

In case, Narrator and Adult are services, the message can receive the endpoint name.

Here, you can see my return is pretty detailed. In my diagrams, I often return values that are relevant to the flow or to the contract.

“God is in the details” — Ludwig Mies van der Rohe

...

Another special kind of message is self-massage.

Self-Message

The self-messaging, obviously, is a call that an object makes to itself. When an Adult is asked by a Narrator, the first calls his cognitive abilities to answer the question.

In the case of self-message, you don’t need a return on it.

Asynchronous Message

The pretty of the asynchronous message is that the caller is not expecting the return message, so it’s not blocked.

Imagine, that Narrator just said to Adult that he drew bao.

The async message is represented by a solid line with an open arrow.

...

So, what we saw so far works great for basic simple flows. Although, we all know that the software we build includes many more operations and much more complexity.

Let’s take a look, how we can model structural controls using Sequence Diagrams.

Structural Controls

The first structural control I want to show you is Conditional control.

Alternative (Conditional) Control

The alternative is a choice (that is usually mutually exclusive) between message sequences. This is modeled by switch or if/else logic in our code:

The Narrator showed bao a drawing and asked, “what is it?”. If an adult saw a hat, the Narrator talked about golf; If an adult saw bao, he felt free to speak about boa constrictors.

Alternative control is represented by a labeled rectangle shape with a dashed line inside.

...

Okay, to show you the controls, I will refresh the novel slightly more for you.

The Narrator, who was a pilot (remember?), crashes in the Sahara desert. While he tries to repair his engine, a little boy (a Little Prince) appears out of nowhere and simply asks him to draw a sheep.

Now, let’s talk about Parallel Control.

Parallel Control

So, our Narrator is an extraordinary person (to put it mildly). However, to his credit, he is multitasking. He can (though with mixed success) repair the engine and communicate with a Little Prince in parallel. I must say, he is a genius!

As you can see, Parallel control notation is pretty similar to the Alternative one. It is represented by a labeled rectangle with a dividing dashed line. However, here each section must be processed, and processes should run in parallel.

...

Last but not least structural control is Looping.

Looping Control

When Little Prince appeared in the story, he asked the Narrator to draw a sheep.

Think about it for a moment. A little boy in a desert, alone… He’s not thirst or hunger. He wants a sheep. Fata-morgana? Genius Narrator stops the world and draws a sheep. So far, so good?

As it turned out, the boy was very fussy. He asked to draw a sheep repeatedly (once it was too big, once too old). Until the Narrator pulled a box and told that the sheep is inside.

The looping control shows that message interaction is going to happen multiple times. There is a guard text underneath the inverted tab that explains the loop.

That’s all! 🐑

...

To look at some of the other UML diagrams I wrote about, head on over to my profile.