Sequence diagrams: notes (left/right/over)

简介 / Introduction

Sequence diagrams model message exchanges between objects, and notes are the primary way to add commentary to those interactions. Both PlantUML and Mermaid support notes in sequence diagrams, each with its own syntax conventions. This post uses the same scenario to demonstrate both engines’ note capabilities side by side.

PlantUML 版

1
2
3
4
5
6
7
8
9
10
11
12
13

@startuml
participant Alice as A
participant Bob as B
participant Carol as C

Note over A: User login
Note left of A: Send auth request
A -> B: POST /login\n{username, password}
Note right of B: Validate credentials
B --> A: 200 OK\n{token}
Note over A,B: Login success
Note over C: Carol observes\nnot part of flow
@enduml

Mermaid 版

1
2
3
4
5
6
7
8
9
10
11
12

sequenceDiagram
    participant A as Alice
    participant B as Bob
    participant C as Carol

    Note over A: User login
    Note left of A: Send auth request
    A->>+B: POST /login<br/>{username, password}
    Note right of B: Validate credentials
    B-->>-A: 200 OK<br/>{token}
    Note over A,B: Login success
    Note over C: Carol observes<br/>not part of flow

对比 / Side-by-side

小结 / Wrap-up

PlantUML’s note syntax is concise, with Note left/right of and Note over serving distinct purposes for complex diagrams. Mermaid’s notes follow the same message syntax, making it easier to learn, though <br/> is required for explicit line breaks. Both support spanning notes across multiple participants to annotate shared state or cross-object context.