なんもわからんコードの調査にシーケンス図を使う

はじめに

コードを調査する時、初めて読む箇所だと時間がかかることがありますよね。
それにはいろいろな要因があると思うのですが、要因の一つとして、処理の流れをイメージしづらいということがあります。というか私はよくそれが原因で時間がかかります。処理がイメージできないまま開くファイルだけが増えていって、余計にわからなくなります。

この前も初めての箇所を調査することがあって¹、試しにシーケンス図を書きながら調査をすると思いのほかうまくいきました²。ここではシーケンス図を使ってよかったことを紹介します。

シーケンス図ってなに？

UMLのひとつです。ちなみに UML とは、オブジェクト指向プログラミングなどのために考えられた図のことで、いろんな種類があります。
UML のひとつであるシーケンス図はこんなやつです。
初見でも、何が書かれているかだいたいわかると思います。

シーケンス図の書き方

シーケンス図の書き方はいろいろありますが、私は PlantUML というコンポーネントを使っています。
私が仕事で使っている GitLab では、コードブロックで以下のようにすると簡単に書き始められます。

```plantuml
(ここに書く)
```

他にも、 VSCode で拡張機能をインストールすると扱うこともできます³。

※ひとつ断っておくことがあって、ここでは、正式な書き方に則ってシーケンス図を書くことはせずに、高度なお絵かきツールとしてシーケンス図を緩く利用しようとしています。ちゃんと UML を学んだ人から見るとデタラメな書き方と感じるかもしれません⁴。すみませんがご了承ください。

PlantUML でのシーケンス図の文法

基本的な文法は
[object] -> [object] : message
です。

ここに詳しく書いてもいいのですが、ちゃんとまとまっているところがあるので紹介します。
-> https://plantuml.com/ja/sequence-diagram

良いところ

シーケンス図の良いところを紹介します。

気軽に書ける

GitLab での話ですが、コードブロックで plantuml とすれば書き始められます。
GitHub でも、Chrome の拡張をインストールすれば使えるようです。

挙動が一目でわかる

完成品を見れば、処理の流れや関連のあるファイルが一目でわかります。また、シーケンス図を知らなくても理解しやすいと思います。

書きながら処理の流れを理解できる

書くこと自体が調査になります。コードを眺めて途方に暮れることもなく、とりあえず手を動かすということができます。

わかっている人に見せると、足りていないところを指摘してもらえる

シーケンス図ができたら、該当の処理を知っているつよつよエンジニアに見せましょう。見せられた人も、いまの理解度を把握できるので、教えやすくなります。

良くないところ

シーケンス図の良くないところを紹介します⁵。

書くのに時間がかかる

書くのに時間がかかります。あるていど知っているコードの場合は、シーケンス図を使わない方が速く調査できたりします。初めて触るコードが複雑な時に候補に挙がる感じです。

ちゃんと書こうとすると学習コストが高い

シーケンス図をちゃんと書こうとすると覚える要素が多いです。気になる方は調べてみてください。

ドキュメントとして残すのには向いていない

ドキュメントとして優秀に見えますが、管理するのに無視できないコストがかかります。チームで書き方を統一しながら、コードを変更するたびにシーケンス図も変更するのは、書く方もレビューする方も、思っている以上に高コストです。
上に書いた学習コストの問題もあるので、ドキュメントとして残すには管理コストの増大を覚悟してください。

おまけ

PlantUML は json や yaml などの可視化もできます。
以下のように書きます。

```plantuml
@startjson
(ここに json を貼りつける)
@endjson
```

```plantuml
@startyaml
(ここに yaml を貼りつける)
@endyaml
```

Qiita ではできないみたいなので、リンクを張っておきます。
-> https://plantuml.com/ja/json
-> https://plantuml.com/ja/yaml

---

以上になります。
利点と欠点を理解して、選択肢の一つとしてご活用ください。

1. 最近は、vuex の巨大なコードを追っているときに途方に暮れました。データ構造とアルゴリズムが好きで、グラフの一種である木が得意なので、 vuex を使わずに @prop と $emit で書いてほしいものです。もちろんこれは嘘です。 ↩

2. なんもわからん。ってなったので息抜きに書いていたら、思った以上に恩恵がありました。 ↩

3. コマンドパレットから ext install plantuml でインストールできます。 java と graphviz が必要なので brew や apt などで入手します。 ↩

4. というか自分がそういう人間の一人だったりします。 ↩

5. 当然ですが、良くないところもあります。万物に有効な銀の弾丸なんてありません。 ↩