UML

What is UML?

UML, short for Unified Modeling Language, is a notation for describing the structure and behavior of software. A diagram can show relationships between types, messages exchanged by objects, or the conditions under which a state changes.¹

UML provides notation for describing structure and behavior. The same relationships can be drawn by hand, in a diagram editor, or with a text-based tool. The choice of programming language, development method, and drawing tool is separate.

Why use it?

Consider a small diagnostic reporter. The error data stays the same, but producing a readable sentence and producing JSON require different formatting. A formatter is the component that converts data into one of these representations.

If the reporter knows every formatting rule, each new format requires a change to the reporter. Instead, the reporter can depend on a shared contract and delegate the conversion to a supplied formatter. Here, the contract is a calling rule: accept a diagnostic and return a string.

A UML diagram helps us see who references whom and what changes when we add a format, before reading all the code. It gives reviewers a shared picture to discuss. Code review and tests then check whether the implementation follows that design.

Choose a diagram for the question

This article covers class, sequence, and state machine diagrams, which appear often in pattern explanations. Start with the meaning of a box and its connecting lines.

Read a class box from top to bottom

• DiagnosticReporter is the type name.

• - formatter: IDiagnosticFormatter is a private property named formatter. Its type follows the colon.

• + report(d: Diagnostic): String is a public operation that accepts d of type Diagnostic and returns a string. An implementation usually represents it as a method.

Before a member, + means public, - private, # protected, and ~ package visibility. A UML package groups elements in a namespace. To map it to a directory or a language's internal visibility, check that language's rules.

The keyword «interface» identifies an interface. Abstract types and operations may be italicized; static features are underlined. A diagram selects the compartments and members relevant to its purpose. Check the code for the complete definition.²

Read the line and its endpoint together

• Generalization: a solid line with a hollow triangle points from a more specific type to a more general type. Class inheritance is a common example.

• Realization: a dashed line with a hollow triangle points from an implementation to its contract. It can show that a class implements an interface.

• Dependency: a dashed line with an open arrow points from a client to the supplier it needs. Using a type as a method parameter is one example.

• Association: a solid line represents a relationship between instances. An open arrowhead marks a navigable end. Storing an object reference in a field is one way to implement such a relationship.

The triangle points to the general type or contract. Think of extends or implements to read its direction. Use arrowheads or the legend to establish an association's navigability. When the diagram leaves that direction unspecified, check the model definition or code for the references.

A hollow diamond marks shared aggregation; a filled diamond marks composition. Both place the diamond at the whole end. Shared aggregation identifies a whole-part relationship, but its precise ownership and lifetime rules must be defined by the model.³

In a composition, a part belongs to at most one composite whole at a time. Deleting the whole also deletes its parts in the model; a part detached beforehand may survive. The implementation must provide the memory cleanup or database deletion needed to enforce those lifetime rules.

Read the formatter example as a whole

• The dashed line and hollow triangle from HumanFormatter to IDiagnosticFormatter show that the readable-text formatter implements the shared contract.

• The solid line from DiagnosticReporter to IDiagnosticFormatter shows that the reporter references its formatter. The role name formatter identifies that property.

• The dashed arrow from DiagnosticReporter to Diagnostic shows that report uses the diagnostic passed to it. A field or association would show a stored reference.

Numbers at the ends of an association are multiplicities. For each reporter, 1 at the formatter end means exactly one formatter. In the other direction, 0..* means that zero or more reporters may reference a formatter. Multiple reporters are allowed to share the same formatter.

0..1 means zero or one; 1..* means one or more. Read the number as the permitted count at this end for one instance at the opposite end. When an association diagram omits the number, consult the model definition for its multiplicity.⁴

The same structure in code

These two programs have the same structure and output. The diagram omits constructors and shows the formatter property on the association. String denotes a string type; {readOnly} marks a property that cannot be directly changed after initialization. Operation and property names follow TypeScript camelCase; the C# code uses Format, Report, and Message according to its naming conventions.

using System;

// Keep the data separate from its display format.
public sealed record Diagnostic(string Message);

// This is the contract that a reporter can call.
public interface IDiagnosticFormatter
{
    string Format(Diagnostic d);
}

public sealed class HumanFormatter : IDiagnosticFormatter
{
    public string Format(Diagnostic d) => "Error: " + d.Message;
}

public sealed class DiagnosticReporter
{
    private readonly IDiagnosticFormatter formatter;

    // Store the supplied formatter instead of constructing one here.
    public DiagnosticReporter(IDiagnosticFormatter formatter)
    {
        this.formatter = formatter;
    }

    // Delegate formatting and return the resulting text.
    public string Report(Diagnostic d) => formatter.Format(d);
}

public static class Program
{
    public static void Main()
    {
        var reporter = new DiagnosticReporter(new HumanFormatter());
        Console.WriteLine(reporter.Report(new Diagnostic("Name not found.")));
    }
}

// Keep the data separate from its display format.
class Diagnostic {
  constructor(public readonly message: string) {}
}

// This is the contract that a reporter can call.
interface IDiagnosticFormatter {
  format(d: Diagnostic): string;
}

class HumanFormatter implements IDiagnosticFormatter {
  format(d: Diagnostic): string {
    return "Error: " + d.message;
  }
}

class DiagnosticReporter {
  // Store the supplied formatter instead of constructing one here.
  constructor(private readonly formatter: IDiagnosticFormatter) {}

  // Delegate formatting and return the resulting text.
  report(d: Diagnostic): string {
    return this.formatter.format(d);
  }
}

const reporter = new DiagnosticReporter(new HumanFormatter());
console.log(reporter.report(new Diagnostic("Name not found.")));

Both programs print:

Error: Name not found.

The caller creates a formatter and supplies it to the reporter's constructor. The reporter stores that reference and delegates conversion to it. A new formatting class can be added without changing Report or report. The Strategy pattern develops this separation in more detail.

A sequence diagram follows one execution

Now draw one call to report in the same example. The class diagram showed relationships between types. This diagram shows calls and replies between the participating objects.

• The boxes at the top name participants. reporter: DiagnosticReporter identifies an object named reporter of type DiagnosticReporter.

• The name box and the dashed line beneath it together form a lifeline. It represents one participant in this interaction.

• Here, a solid line with a filled arrowhead is a synchronous call: its caller waits for it to return. A dashed line with an open arrowhead is a reply.

• A narrow rectangle on a lifeline marks an execution. The call to human occurs within the time that reporter is handling its own call.

Follow the calls and replies from top to bottom. Read the order of events on each lifeline together with the sending and receiving of messages; independent events on separate lifelines follow their own local order. Treat vertical spacing as layout, and use explicit time values or constraints to read elapsed time.⁵

A state machine diagram shows allowed changes

Consider a music player. Pressing play while stopped starts the music; pausing during playback keeps the current position. We will model three states—Stopped, Playing, and Paused—and draw where each button press takes the player.

• The small filled circle marks the initial entry. This player starts in Stopped.

• Rounded boxes represent states: Stopped, Playing, and Paused.

• An arrow is a transition. play moves Stopped to Playing; pause moves Playing to Paused. resume continues playback, and stop returns either Playing or Paused to Stopped.

A transition can be labeled event [guard] / effect. Labeling the arrow from Stopped to Playing play [trackLoaded] / startAudio() means that a play event starts the audio and enters Playing when a track is loaded. Add guards and effects where the model needs them.⁶

A state diagram shows the behavior rules. The State pattern organizes the implementation by putting state-specific behavior in separate objects. A small model can use an enum and conditionals; larger state-specific behavior may benefit from that object-based separation.

When drawing your own

• Choose one question first. Who references whom and who calls whom in what order need different views.

• Select the types and objects that answer the question. Include constructors and helper methods when they help explain the relationship.

• Check the meaning of solid lines, dashed lines, triangles, and diamonds, then add the necessary role names and multiplicities. Explain any nonstandard notation in a legend.

• Compare the diagram with the code. Is a reference stored, is a type used only as a parameter, or is an interface implemented? Update explanatory diagrams when the code changes.

Example environment: C# was run on .NET 10; TypeScript was compiled for ES2022 and run with Node.js.

Related reading

• Strategy pattern: interfaces and interchangeable implementations

• State pattern: state-specific behavior and transitions

• OMG UML 2.5.1: specification and version record