How to Write Uml Diagram Codes: a Step-by-Step Guide for Beginners

Most developers learn UML diagrams by staring at finished images boxes, arrows, relationships but never actually learn how those diagrams were written as code. That gap matters. When you know how to write UML diagram codes step by step, you can version-control your designs, collaborate through pull requests, and generate diagrams automatically instead of dragging shapes around in a drawing tool. This article walks you through the process from scratch, so you can go from a blank text file to a working diagram in minutes.

What Does Writing UML Diagram Code Actually Mean?

UML diagram code is a plain-text representation of a diagram using a specific syntax. Instead of drawing boxes and arrows manually, you write structured lines that describe classes, relationships, actors, and activities. Tools like PlantUML, Mermaid, and UMLet then parse that code and render the visual diagram for you.

This approach is sometimes called "diagrams as code" or "textual UML notation". It treats your architecture diagrams the same way you treat source code editable, diffable, and reproducible.

Why Should You Write UML Diagrams as Code Instead of Drawing Them?

Drawing tools like Lucidchart or Draw.io work fine for quick sketches. But they create problems when your project grows:

No version control. Binary or proprietary files are hard to diff or merge.
No reuse. You can't programmatically generate or update diagrams from your codebase.
Slow iteration. Moving boxes and re-laying arrows takes time every time a design changes.
Poor collaboration. Team members need the same tool and often the same license.

Writing UML code solves these issues. You store diagrams as .puml or .mmd files, track them in Git, and regenerate images in your CI pipeline. If you're comparing different UML diagram types and their coding symbols, having them all as text makes side-by-side comparison much easier.

Which UML Diagram Types Can You Write as Code?

Not every diagram type is equally well supported in every tool, but most textual UML tools handle the common ones:

Class diagrams describe classes, attributes, methods, and relationships
Sequence diagrams show interactions between objects over time
Use case diagrams capture user goals and system boundaries
Activity diagrams model workflows and decision logic
State diagrams represent object states and transitions
Component diagrams show system modules and dependencies
Deployment diagrams map software to physical infrastructure

Each type uses slightly different syntax. The core steps below apply broadly, but you'll adjust keywords and structure depending on what you're modeling. Our UML diagram syntax and notation breakdown covers these differences in more detail.

How Do You Set Up Your Environment for Writing UML Code?

Before writing any diagram code, get your tooling ready:

Choose a textual UML tool. PlantUML is the most popular and supports the widest range of diagram types. Mermaid is lighter and works natively in Markdown (including GitHub). Pick one to start with.
Install a renderer. For PlantUML, you need Java and the PlantUML JAR file, or you can use the PlantUML online server for quick testing. For Mermaid, use the Mermaid Live Editor or a browser extension.
Set up your editor. VS Code has extensions for both PlantUML and Mermaid that give you syntax highlighting and live preview. This saves a lot of guesswork.
Create a diagram folder. Put your .puml or .mmd files in a dedicated directory so they're easy to find and maintain.

What Are the Steps to Write a UML Class Diagram in Code?

Class diagrams are the most common starting point. Here's how to build one from scratch using PlantUML syntax:

Step 1: Define Your Classes

Start by listing the classes your system needs. Use the class keyword followed by the class name in curly braces.

class User { } creates a box labeled "User"
Add attributes inside the braces: - name: String
Add methods: + login(): boolean

Use + for public, - for private, # for protected, and ~ for package-private visibility.

Step 2: Define Relationships Between Classes

Now connect the classes using arrows:

Association: User --> Order (solid line, open arrow)
Inheritance: Admin --|> User (solid line, closed triangle)
Composition: Order -- OrderItem (filled diamond)
Aggregation: Team o-- Member (open diamond)
Dependency: Service ..> Repository (dashed line)
Interface implementation: User ..|> Authenticatable (dashed line, closed triangle)

Each arrow type has a specific meaning. Getting these wrong is one of the most common mistakes in UML diagrams we cover more of these in our guide to UML diagram syntax and notation.

Step 3: Add Multiplicity and Labels

Multiplicity tells readers how many instances are involved in a relationship. Add labels near the arrows:

User "1" --> "" Order : places means one user places many orders
Order "1" --> "1.." OrderItem : contains means an order has at least one item

Step 4: Group Classes into Packages (Optional)

If your diagram has many classes, organize them into packages:

package "Domain" { class User class Order }
package "Services" { class OrderService }

Step 5: Render and Review the Diagram

Run your code through PlantUML (paste it into the online server or run the JAR locally). Review the output. Check that:

All classes appear correctly with their attributes and methods
Arrows point in the right direction
Multiplicity labels are readable
No connections are missing

For a complete Java-based class diagram example, see our UML class diagram code example in Java.

What Does a Full PlantUML Class Diagram Code Look Like?

Here's a complete working example combining all the steps above:

@startuml
class User {
- name: String
- email: String
+ login(): boolean
+ logout(): void
}
class Order {
- orderId: int
- total: double
+ calculateTotal(): double
}
class OrderItem {
- quantity: int
- price: double
}
User "1" --> "" Order : places
Order "1" -- "1.." OrderItem : contains
@enduml

Paste this into the PlantUML online server and you'll get a clean, labeled class diagram with proper UML notation.

How Do You Write Other UML Diagram Types as Code?

The pattern is always: declare elements, define relationships, add details, render. But the keywords change per diagram type.

Sequence Diagrams

Use actor, participant, and arrow syntax like -> for synchronous calls and --> for return messages. Example:

actor User
participant Controller
participant Service
User -> Controller: login()
Controller -> Service: authenticate()
Service --> Controller: true
Controller --> User: success

Activity Diagrams

Use start, stop, if/else, and :activity description; syntax. These are great for modeling business logic and workflows.

Use Case Diagrams

Use actor, usecase, and --> arrows. Enclose actors and cases inside rectangle blocks to show system boundaries.

Each type has its own nuances. The comparison table in our UML diagram types and symbols guide breaks down the syntax differences side by side.

What Common Mistakes Do People Make When Writing UML Code?

Using the wrong arrow type. Inheritance uses --|>, not -->. Composition uses --, not --. Mixing these up changes the meaning entirely.
Forgetting multiplicity. Without it, readers can't tell if a relationship is one-to-one or one-to-many.
Writing too many classes in one diagram. Keep each diagram focused on one concern. If you have 30+ classes, split into multiple diagrams organized by package.
Skipping the rendering step. Always preview your diagram before committing it. Syntax errors produce confusing or missing output.
Using inconsistent naming. Pick a convention (e.g., PascalCase for classes, camelCase for attributes) and stick with it across all diagrams.
Ignoring direction. PlantUML auto-layouts can place arrows in unexpected directions. Use left to right direction at the top of your file if needed.

How Do You Keep UML Diagram Code Maintainable Over Time?

As your project grows, your diagrams will too. Here's how to keep them manageable:

One diagram per file. Name files clearly: order-management-class.puml, not diagram3.puml.
Use includes. PlantUML supports !include to share common elements (like a shared theme file) across diagrams.
Standardize themes. Create a skinparam file for fonts, colors, and arrow styles so all diagrams look consistent.
Automate rendering. Add a build step that converts .puml files to .svg or .png using PlantUML's CLI or a CI plugin.
Review diagrams in pull requests. Treat diagram code like any other code change. Review it for accuracy and clarity.

Practical Checklist: Writing Your First UML Diagram Code

Use this checklist the next time you need to create a UML diagram from code:

Pick your diagram type (class, sequence, activity, etc.)
Choose your tool (PlantUML, Mermaid, or another textual notation)
List all elements you need (classes, actors, components)
Define each element with its attributes and methods
Draw relationships using the correct arrow syntax
Add multiplicity and role labels where needed
Organize into packages or groups if the diagram is large
Render the diagram and check it visually
Fix any layout issues (try left to right direction or top to bottom direction)
Commit the code file and the rendered image to version control

Next step: Pick one diagram from your current project a simple class diagram or a login sequence diagram and rewrite it as PlantUML code this week. You'll be surprised how much faster the second diagram goes.