Qiita での UML 記述（その２）

Qiita で PlantUML および mermaid が使用できるようになったということで軽く比較したいと思います。
それぞれの正式な書式については公式サイトをご確認ください。

cf. 前回（シーケンス図）

アクティビティ図（フローチャート）

cf. PlantUML legacy
cf. PlantUML Beta
cf. mermaid

PlantUML.1

PlantUML でのアクティビティ図は旧版（legacy）と新構文（Beta）がありますが、Qiita では旧版のみサポートしているようです。
PlantUML 旧版（以下、PlantUML）では進む方向を逐次指定することが可能です。

```plantuml
(*) -up-> "First Activity"
-right-> "Second Activity"
--> "Third Activity"
-left-> (*)
```

mermaid.1

mermaid のアクティビティ図は流れの方向に応じた種類あり、基本的には左から右に進む flowchart LR と上から下に行く flowchart TBを使うことになると思います。
これらのほかに TD（TB と同等）、BT（下から上）、RL（右から左）があります。試した限りでは、５つとも Qiita で使用できるようです。
また、１行で連続して記述できるなど、慣れていれば書きやすい機能だと思われます。

```mermaid
flowchart LR
   A -- text --> B -- text2 --> C
```

```mermaid
flowchart TB
   A -- text --> B -- text2 --> C
```

PlantUML.2

条件分岐の記載ができます。
コメントで改行をしたい場合は \n を挟むことで対応できます。

```plantuml
(*)  --> "check input"
If "input\nis verbose" then
--> [Yes] "turn on\nverbosity"
--> "run command"
else
--> "run command"
Endif
-->(*)
```

mermaid.2

mermaid も当然条件分岐が記載できるのですが、分岐の要素に条件文を書くと途端に巨大な菱形になり、見た目はあまりよろしくありません。
菱形の外にコメントを記載したくてもその方法はないようです。
コメントで改行をしたい場合は <br> を挟むことで対応できます。

```mermaid
flowchart TB
    A[Start] --> B(check input)
    B --> C{input<br>is verbose}
    C -->|YES| D(turn on<br>verbosity)
    C -->|NO| E(Run command)
    D --> E
    E --> F[End]
```

アクティビティ図に関しては mermaid よりも PlantUML の方が見やすいものが書けると思います。

状態遷移図

cf. PlantUML
cf. mermaid

上記の公式サイトを見ていただくと分かりますが、PlantUML の状態遷移図はかなり詳細な記述が可能となっています。
可能となっていますが、逆に公式に記載されているような図を誤りなくコーディングするのはかなりの力量が求められますし、Markdown で手打ちをするよりは専用のエディタを使用した方が良いと思われます。

PlantUML.3

```plantuml
hide empty description
[*] --> Still
Still --> [*]

Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```

mermaid.3

mermaid では stateDiagram と stateDiagram-v2 という新旧の書式がありますが、現在は公式サイトでは stateDiagram-v2 のみ解説がされており、Qiita では両方とも対応しているようなので、ここでは stateDiagram-v2 についてのみ記載します。

```mermaid
stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

PlantUML.4

注釈の記載が可能です。

```plantuml
[*] --> Active
Active --> Inactive

note left of Active : this is a short\nnote

note right of Inactive
  A note can also
  be defined on
  several lines
end note
```

mermaid.4

mermaid でも注釈を記載できますが、指定した位置に表示されないことがあります。

```mermaid
stateDiagram-v2
    [*] --> Active
    Active --> Inactive
    Inactive --> Active

    Active: this is a short<br>note
    note left of Active : this is a short<br>note
    note right of Inactive
        A note can also
        be defined on
        several lines
    end note
```

まとめ

前回のシーケンス図は甲乙つけがたいところがありましたが、今回のアクティビティ図（フローチャート）と状態遷移図については出力結果だけを見ると PlantUML の方が見やすい図表として描画されると思います。

mermaid も一見綺麗なものになるのですが、小回りが利かないものになり、痒い所に手が届かない気がします。

また、状態遷移図のところで書いた通り、本格的な UML 図を書くのであれば専門のツールを使用した方が圧倒的に便利なので、Markdown で記載するのは飽くまで簡易的なものと割り切った方が良いとは思います。

（いつ頃正式採用されたかは知りませんが、）Qiita で PlantUML と mermaid が採用されて UML が記載しやすくなったのは確かだと思うので、機会があれば利用していきたいと思います。