Why we need Sequence Diagrams:
Pull requests should be in general small in size, so to give the reviewer the chance to focus more effectively on the code. But from my experience, the most important thing is not the size of the Pull Request but the context. We should try to make our reviewer understand not only which feature we are adding, but also a brief overview of how the code in the Pull Request solves that.
For the first part, understanding what we want to achieve, we can provide a brief description and a link to the issue (if we are using any project tracking system). But for how we solve it, we can use a sequence diagram when our code has objects that interact with each other.
Definition of Sequence Diagram:
According to Wikipedia:
A sequence diagram shows object interactions arranged in time sequence. It depicts the objects and classes involved in the scenario and the sequence of messages exchanged between the objects needed to carry out the functionality of the scenario
How to make a Sequence Diagram:
There are many tools online that can help us draw a sequence diagram. In this article, we will use PlantUML.
Let’s first understand how to use the PlantUML, and as a next step, we can draw the Sequence Diagram for this repo: https://github.com/Fragki/Clean-Architecture-Simple-Example.
There are many options to run the PlantUML code. In this article, we will use the following link https://www.planttext.com/.
Let’s start by opening the Panttext. Initial we show an empty diagram.
A valid diagram should start with @startuml and end with @enduml. All the code has to be placed between these two tags.
We will begin by drawing the sequence form the moment when the user taps on a number button. As we notice in the code the “didSelectNumber” method is called on the OddOrEvenViewController.
By writing the following line
“OddOrEvenViewController” -> “OddOrEvenViewController” : didSelectNumber
and tapping on the refresh button we see our first interaction line in the diagram.
Then the OddOrEvenViewController calls the method “calculateNumber” on the OddOrEvenInteractor.
“OddOrEvenViewController” -> “OddOrEvenInteractor” : calculateNumber
When the method calculateNumber is called on the OddOrEvenInteractor, the OddOrEvenInteractor calls the OddOrCalculator to ask for the result.
“OddOrEvenInteractor” -> “OddEvenCalculator” : isEven
After the OddEvenCalculator calculates the result, it sends it back to the OddOrEvenInteractor.
“OddEvenCalculator” –> “OddOrEvenInteractor”
Then the OddOrEvenInteractor calls the “update” method on the OddOrEvenPresenter.
“OddOrEvenInteractor” -> “OddOrEvenPresenter” : update
Finally theOddOrEvenPresenter calls the “update” methdo on OddOrEvenViewController and the V.I.P. cycle closes.
“OddOrEvenPresenter” -> “OddOrEvenViewController” : update
It is always useful to add a title to our diagrams. Let’s add on by writing the following line just after the @startuml:
title: Calculate Odd or Even Use Case
Also, a comment sometimes can be very useful. We can add one by writing the following line:
note left: End of V I P cycle
Resources:
http://plantuml.com/sequence-diagram
https://www.visual-paradigm.com/guide/uml-unified-modeling-language/what-is-sequence-diagram/
