UML Made Easy with PlantUML & VS Code

Introduction

UML stands for Unified Modeling Language. It’s a general-purpose modeling language to standardize a way to visualize the architecture of software systems. It was developed by Grady Booch, Ivar Jacobson and James Rumbaugh at Rational Software in 1994–1995. Later in 1997, it was adopted as an industry standard.

UML is a way to express software component design in terms of widely accepted graphical notations. It’s often good to have a graphical model before you start coding out the model itself using any textual programming languages. Later on, the model can also be used for documentation purposes as well. The usefulness of UML can be described with the following real-life scenario: When we onboard new developers, we don’t want them to read every line of code and guess what it is all about; we want to give them an overview of the whole system. Likewise, when we want them to work on a feature, we don’t want them just to get briefed verbally; we want them to have a blueprint of the required feature, hence the use of UML diagrams.

Following the approach mentioned above can ease out a lot of headaches and misunderstandings about the systems. Often design flaws also get caught up front in this process.

UML starts out as a sketch on a whiteboard having minimal amount of details in order to have a design discussion with team members. When a decision is finalized, a relevant sketch is put onto a more sophisticated tool where the end result works as a blueprint for a programmer to work with.

Basic UML Types

There are a bunch of UML diagrams to choose from depending on your use case. However, they are categorized into sets of Structural and Behavioral UML diagrams.

Structural diagrams reflect the structure of a system whereas the behavior diagrams describe how the system reacts under certain actions. In total, there are 14 UML diagrams; some are important while some are less important. They are as follows...

Structural UML Diagram

• Class diagram
• Object diagram
• Component diagram
• Deployment diagram
• Package diagram
• Composite structure diagram
• Deployment Diagram

Behavioral UML Diagram

• Usecase diagram
• Activity diagram
• Sequence diagram
• State diagram
• Communication diagram
• Timing diagram
• Interaction overview diagram

We will only code up a few different ones. Follow along and you will find out what I meant by coding out diagrams.

Available Tools for Modeling

For modeling, simple pen and paper can do the trick. However, for long lasting documentation and frequent editing purposes, you might want to look for bit more of a professional grade tool. The choice of a tool may come in the form of a desktop, online or just an IDE (Integrated Development Environment) plugin. Some may ask you for monthly/yearly subscriptions while some are freeware. A few well-known tools are as follows:

PlantUML to the Rescue

While Visio and draw.io both seem like good options, one needs a few bucks after its free trial period and another needs a constant internet connection. That’s why PlantUML sounds great if you are just starting and struggling to make a decision.

PlantUML takes on the chore of diagramming a bit differently. Unlike dragging and dropping different shapes from the toolbox and connecting them, you express your diagram in terms of a pseudo programming language. The language is very easy to understand and doesn’t take much time to get along.

Visual Studio Code Integration

PlantUML supports a wide range of IDE integrations. All the supported IDEs are listed on the official PlantUML website, http://plantuml.com/running.

We opt for VS Code since it’s running hot lately and there is no sign of stopping it. Before installing PlantUML extension on VS Code, make sure you have the following prerequisites:

• Java
• GraphViz

For Windows users, if you have Chocolatey (package manager for Windows), you can make the installation process easier with the following command:

choco install plantuml

You can search and install PlantUML extension from the Extensions tab. It’s available in the Visual Studio Marketplace. You can also use VS Code command palette by pressing Ctrl +Shift + P on Windows or Command + Shift + P on Mac and type in:

ext install plantuml

Coding Up Few Models

As mentioned earlier, in PlantUML we use a pseudo-programming language to generate diagrams. This code file can have one of the following file extensions:

*.wsd, *.pu, *.puml, *.plantuml, *.iuml

To have a test run, create a file with any of the mentioned extensions and paste the following code:

@startuml
scale 3
Alice -> Bob : test
@enduml

Press Alt + D or Option + D to get a preview of the generated diagram.

Class Diagram

A class diagram represents objects in a system and various relations among them. It’s the most common UML diagram you will ever encounter while designing a system. A class contains attributes which are merely fields, properties, and operations that are simply methods. Both attributes and operations have their own accessibly modifiers (visibility) expressed in terms of operators such as (+, -, ~, #) e.g. +field1 means there is a field in the class which is public.

A class diagram for administering a bootcamp may have the following architecture:

The corresponding PlantUML pseudocode is as follows:

@startuml
scale 2
class Event {
    +startTime: DateTime
    +venue: string
    +registrationClosed: boolean
    -notifyAttendes()
}

class ApplicationUser {
    -userName: string
    -password: string
    +isLocked: boolean
    -suggestRandomPasswod()
    +changeProfilePic()
}

class Speaker {
    +openForSpeaking: boolean
    -callForAction()
    +applyAsSpokePerson()
}

class Topic {
    +title: string
    +sourceCodeUrl: string
    +downloadMaterials()
}

class Attendee {
    -eventAttended: number
    -suggestEventBasedOnPreference()
    +registerForTicket()
}

ApplicationUser <|-- Speaker
ApplicationUser <|-- Attendee
Speaker "1" *-- "*" Topic
Event "1" o-- "*" Speaker
Event "1" o-- "*" Attendee
@enduml

Some of the symbols in the diagram are worth mentioning. They are described in a more tabular manner.

Activity Diagram

Activity diagrams are widely used to describe the business process and flow of work. It looks similar to a flowchart. However, they support both sequential and parallel behaviors.

Activity diagrams may or may not be organized in vertical swim lanes. Swim lanes indicate the participation of one or more actors in the workflow. In an activity diagram, a complete black circle denotes the start of the process while a hollow circle with a black dot inside denotes an end. Polygons are often decision-making phases. Horizontal bars denote that two or more actions are happening in parallel.

An activity diagram for an online game purchasing system may have the following process flow:

The corresponding PlantUML pseudocode is as follows:

@startuml
scale 2
start
:Add games to cart;
:Checkout;
:Check cookie;
while (if cookie?) is (is invalid)
:Show login form;
endwhile
fork
:Mail invoice;
fork again
:Load games;
end fork
:Install and play;
stop
@enduml

Exporting for Documentation

PlantUML supports exporting diagrams into different file formats. The following are some of the supported types:

*.png, *.svg, *eps, *.pdf, *vdx, *.xmi, *scmi, *html, *.txt, *.utxt, *.latex

The default exporting location is set to Desktop. However, following VS Code user settings will make sure you have both the pseudocode and diagrams live alongside your source code directory in a folder named “docs”.

"plantuml.diagramsRoot": "docs/diagrams/src",
"plantuml.exportOutDir": "docs/diagrams/out"

You'll get export results like:

Project Folder/  
    docs/        
       diagrams/            
           src/                
               architecture_overview.wsd            
           out/                
               architecture_overview.png

Conclusion

This article barely scratches the surface of UML. Discussion of UML is broad and takes a bit of time to get along. Only a couple of diagrams are discussed from a top level and the focus was more on PlantUML than UML itself. Further reading is suggested for a better understanding of the ins and outs of the UML. The following books may help you get up and running:

• Learning UML 2.0: A Pragmatic Introduction to UML
• UML Distilled: A Brief Guide to the Standard Object Modeling Language (3rd Edition)