Chris Meudec's Lean and Agile UML Reference

Chris Meudec

First Version March 2014 - Latest Version February 2017


Recommended Tool

Use Case Diagram

Package Diagram

System Sequence Diagrams

Domain Model Diagram

Object Diagrams

Sequence Diagrams

Design Class Diagrams

State Machine Diagrams


This is my version of a lean reference and agile usage guide of the UML; I was inspired by Allen Holub’s version of course.

My aim is to provide a lean reminder of the UML needed 90 percent of the time within an agile approach and also provide basic guidelines: it is not to teach the UML nor how to use it.

Feel free to provide comments directly using Google Doc’s commenting mechanism on the Google Doc version of this UML lean reference. And if you are reading the Google Doc version you can also access the equivalent web version of this UML Lean Reference.

I use UML notes to explain the basics of the diagrams:


The diagrams below are just examples to illustrate the notation: they are not related to each other, or in other words, they do not belong to the same system and are used for illustration only.

Why? Why do we need agile UML? Does using the UML mean abandoning Agility? Are these things not mutually exclusive? Well I personally do not think so nor does this guy nor does Martin Fowler as he explains in his ‘Is Design Dead?’ keynote address at the XP 2000 conference.

Recommended Tool

In an agile environment I recommend UMLet because it is nearly as quick as sketching on a whiteboard.


How to use the UML within an agile process? Some guidelines:

Use Case Diagram

What For: To quickly represents the functionalities of the system under consideration, its context (the actors), and the key ways it will be used (the use cases).

Dos: Do keep them simple; Do identify your actors; Do identify the keys ways actors will use your software to give you your ‘use cases’; Do link actors and use cases with simple lines without arrowheads nor labels; Do name your use cases starting with a verb; Do add the boundary box (everything within it is a system, or subsystem, that you have to develop).

Do Nots: Do not add arrows; Do not add labels on the link; Do not link use cases with one another; Do not add ‘System’ as an actor.

Use Case Diagram.png

Package Diagram

What For: To give an overview of the overall code’s organisation: its architecture. A typical architecture is a layered architecture (mainly with three layers: a view layer, a domain layer and a services layer) so that some separation of concern is achieved and the code does not end up in a big mess and to allow implementation of a distributed system.

Dos: Do choose a high level architecture and maintain a separation of concerns between your layers; Do feel free not to create a package diagram initially: they are mostly useful for larger systems; Do add dependencies between packages (downwards only if you can in a layered architecture).

Do Nots: Do not go too deep and add too many details initially: in fact just the layers and the main inner packages are sufficient at first.

Package Diagram.png

System Sequence Diagrams

What For: They formalise the interactions between the actors and the system within a use case. Therefore there should be one System Sequence Diagram per use case. Their main benefit is to clarify use cases and identify the events (and arguments) sent from the actors to your system.

Dos: Do create them they as they are very useful; Do change your detailed use cases if necessary to match your System Sequence Diagrams (and vice-versa of course as consistency across all artefacts is important); Do only show the System to develop as a single entity as a black box and the actors involved in the use case only; Do try to find descriptive names for your events generated by the Actors; Do add arguments to your events; Do use camelCase (for increased readability) for your event names and arguments; Do focus on the events generated by the actors and received by your system.    

Do Nots: Do not focus too much on returned information from the system; Do not focus too much on internal processes within the system; Do not add a database as an actor (unless it is an external database independent from your solution)

System Sequence Diagrams.png

Domain Model Diagram

What For: A static diagram (i.e. representing the code’s breakup in terms of class) which shows the initial classes of the domain layer of a system, their attributes and relationships. A domain model is a simplified class diagram; It leads to a Design Class Diagram later on after the dynamic design has taken place. It is typically only created during the first iteration: later iterations add onto the Design Class Diagram as necessary;

Dos: Do create one for your first iteration and update your design class diagram after the first iteration; Do use camelCase for the attributes’ names; Do name the associations meaningfully to improve communication between team members; Do ensure that all your data members are pure data values (i.e. do not represent objects): use associations between classes to represents relationships between objects; Do use camelCase for your attributes; Do add multiplicity information (is it a 1 or * type of association between objects?); Do simulate what will happen at runtime by reading the detailed use cases and updating an object diagram (see below).

Do Nots: Do not include GUI classes they belong to the view layer; Do not have a class with an s at the end, a class represents one entity, so it’s Square not Squares. Do not have spaces in your class names and ensure they start with a capital letter; Do not include methods; Do not add arrows on the associations between classes; Do not add role names; Do not worry too much about the type of attributes; Do not worry about members’ types of visibility (e.g. public, private or protected); Do not add data members that are an object (or represent an object via using a unique id) or collection of objects: use associations between classes to represents relationships between objects;  Do not worry too much about multiplicity differences between 0..1 and 1 (nor between * and 1..*); Do not worry too much about the differences between composition vs. aggregation vs. normal associations; Do not add Database classes: they belong to the services layer;

Domain Model.png

Hotel System Domain Model

(you may have to zoom in or right-click the image and select ‘Open image in new tab’)

Object Diagrams

What For: Object diagrams can be used in an informal way to animate a domain model diagram or design class diagram. Instead of looking at classes, objects are represented and we can simulate the behaviour of the system according to various scenarios (e.g. various use cases) by showing the state of the our objects to ensure that the classes proposed will be able sustain the expected behaviour of the system. Because this is such a dynamic diagram and not at all a documentation artefact I recommend the use of whiteboard rather than a software tool.  

Dos: Do simulate the behaviour of your proposed objects according to your domain model and design class diagram and try to discover problems when acting out your user stories (or use cases); Do be consistent with your domain model or design class diagram when creating object model and update them as necessary.

Do Nots: Do not use object diagrams as documentation: learn from them and update your domain model and design class diagrams as appropriate, then discard them; Do not be fussy on how your object diagrams look, just use a whiteboard and different colour pens; Do not invent classes, attributes nor associations (i.e. elements that do not exist in your class diagram) when creating object diagrams: be consistent.

Object Diagram HotelSystem 1 Start.jpg        Object Diagram HotelSystem 2 Login.jpg

      Hotel System with some Tourists (ts) logged in                        Hotel System after ‘Jane’ logs in via a Session s3

Object Diagram HotelSystem 3 Rooms.jpg                Object Diagram HotelSystem 4 Reservation.jpg

           Hotel System with some Rooms        (rs)                              Hotel System after ‘Jane’ has reserved Room ‘A1’

Sequence Diagrams

What For: Sequence diagrams show the interactions, the collaborations, between objects via method calls: they represent the dynamic aspect of a system—the algorithms. Using the classes discovered so far, the System must handle the individual system events generated by the Actors (typically from the GUI for human actors or from a network for other non-human actors) and create an algorithm involving many types of objects to fulfil the responsibilities that the system must implement. The notation is identical to the notation for System Sequence Diagrams but is used to show the interactions between individual objects (low level) rather than between the System and its actors (high level). These diagrams are, unsurprisingly, the most difficult to create.

Dos: Do create a separate Sequence Diagram for each event received by your System from its actors; Do start your Sequence Diagram by the event generated by the actor; Do try to find descriptive names for your methods; Do add arguments to your methods; Do use camelCase for your method names and arguments; Do differentiate in your notation between a simple object and a collection of objects.

Do Nots: Do not invent types of objects that do not exist according to your class or domain diagram; Do not increase the coupling of your design by allowing an object to call the method of another without a reference to it according to your domain model.

Sequence Diagram.png

Below is an example of the create message in Sequence Diagrams to create instances. Implicitly the create message calls the constructor and, this is typically not shown, return a reference of the newly created object that is kept locally within the caller.

Lean UML Create Sequence Diagram.png

Finally iterating over a collection of objects is quite common and is illustrated below.

Lean UML Iteration Collection Sequence Diagram.png

Design Class Diagrams

What For: A Design Class diagram shows your classes, their attributes, their methods and their relationships: it is a summary of the structure of your classes and thus your code. It uses the same notation as Domain Models but add much more details, for example: methods are added, associations are transformed by adding visibility arrows and replacing association names with role names.

Dos: Do take your domain model as a starting point (or your existing Design Class diagram if you have one from a previous iteration); Do add the necessary method according to your Sequence Diagrams; Do add role names and visibility information as necessary from your sequence diagrams; Do maintain consistency with you other diagrams by modifying them if necessary.

Do Nots: Do not add classes never mentioned before; Do not show getters and setters in the list of methods: they are of little documentation interest; Do not show constructors unless their arguments are of interest.

Lean UML Design Class Diagram.png

State Machine Diagrams

What For: State Machine Diagrams show, for objects whose behaviour depends on their past, the range of possible behaviour and the events that trigger that change of behaviour. They are a great way to explore or document object behaviour over time.


Do Nots: Do not create a state machine diagram unless you need to: most of the time they are not necessary;

State Machine Diagram.png

 Christophe Meudec 2014-2038