こんにちは丸山@h13i32maruです。システム全体を簡単な図とテキストでまとめる「ARCHITECTURE.md」というものを最近知りました。これは良さそうと思い、JasperのARCHITECTURE.mdを書いてみました。
jasperapp/jasper/ARCHITECTURE.md
ARCHITECTURE.md自体の目的は「プロジェクトへの新規参加者が全体像の把握を効率的に行えるようにする」という感じです。書き方の指針や注意点などは考案者による記事を見てもらうのがよさそうです。また良いサンプルとしてrust-analyzerというOSSのARCHITECTURE.mdが紹介されています。
- https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html
- https://github.com/rust-analyzer/rust-analyzer/blob/d7c99931d05e3723d878bea5dc26766791fa4e69/docs/dev/architecture.md
- https://gigazine.net/news/20210210-architecture-md/
今回は実際に書いてみたときの「気をつけたこと」「感想」を簡単に残しておきます。Jasperのアーキテクチャに興味がある方がいればもちろんARCHITECTURE.mdを見てください😝
気をつけたこと
ARCHITECTURE.mdも一種のマニュアルだと思うので、読者が対象（今回はアーキテクチャやコード）についてのメンタルモデルを獲得できることを意識しました。 このあたりの話は以前に会社のブログに書いたので興味あれば見てください。
まずは読者がすでに持っているメンタルモデルを想定しておきます。JasperのARCHITECTURE.mdを読むくらいなので、Jasperを利用している人でかつプログラマーのはずです。なので今のメンタルモデルとしては以下のようなものを想定しておきます。
見たいIssueの条件をStreamで作っておくと、Issueの更新が通知される。裏側は多分GitHub APIに定期的にアクセスしてる。もしくは常時接続や更新を通知してくれる便利なGitHub APIがあるのかもしれない
その読者がARCHITECTURE.mdを読み終わったら、「不具合の調査や機能追加をするために、どのあたりのコードから見ればよいのか、探し方がわかる」という状態になるのを目指します。コードをスラスラ読めるとか、当該のコードにピンポイントでアクセスできるとかはちょっとハイレベルな目標なので今回は考慮しません。なので獲得してもらうメンタルモデルとしては以下のレベルくらいがよさそうです。
主要なコンポーネントはFooとBarと...で、それらはxxな感じで関連している。あの機能に関しては多分○○あたりのコードから読み始めるとよさそう
ということで、このメンタルモデルを獲得できるような内容になるように意識します。具体的には現在もっているメンタルモデルに直接関わるコンポーネントとそこから一段潜ったコンポーネントについて説明することにしました。あとはJasperはElectronで作っている都合上、Electron自体のプロセスモデル（Main/Renderer/IPC)については記載さざるを得ません。
その他に気をつけた細かいところはこんな感じです。
- あまり詳細に書きすぎない
- メンテナンスコストを抑えて、コードの詳細が変わってもARCHITECTURE.mdを変更しなくても良くするため
- それと読者のメンタルモデルを考慮すると、詳細度が高すぎると理解の妨げになるため
- なるべく「何故そうしたか」を書く
- メンタルモデルを獲得し、それが頭に定着しやすくするため（丸暗記より、演繹的に導けるほうが覚えやすい）
- 本文中に書くと読みづらくなるものはFAQにまとめた
- ARCHITECTURE.mdではコードへ直接リンクは貼らないほうがよいらしいが、今回は貼ってみた
- ARCHITECTURE.mdを読みながら具体的なコードにもすぐに目を通せたほうが、更に次の段階に行きやすいと思ったから
- 図はGoogle図形描画を使った
- ポンチ絵を書くだけなら十分だし、オンラインですぐに編集できるので便利
感想
アーキテクチャ図を書くことが一番良かったです。今までは頭の中にしかなかったものが目視できるようになると、気づくことがあります。例えば今回だと、ポーリングもユーザイベントと同じレイヤーとして扱ったほうが理解しやすそうなのでディレクトリ構造を少し修正したほうがいいなと気づきました。それとJasper v1.0で大幅にアーキテクチャを変更したので、その整理という意味でも良かったです。
それと仕事でこういうドキュメントを書くことがあれば、その練習にもなりそうです。あとは単純に満足感がありました。
追記
UMLは実装や設計を具体的に助けるものという印象があり、かなり実装詳細によってるのかなーと思います。一方でARCHITECTURE .mdは新規参加者が全体像を掴むことを目的としてるので、正確性には多少かけたとしてもざっくり把握できることを優先してるように思いました。 https://t.co/Asxpavylrd
— Ryo Maruyama (@h13i32maru) 2021年2月20日
なのでARCHITECTURE .mdの次にUMLやもっと詳細度の高いドキュメントをみるのがよさそうです。UMLやARCHITECTURE .mdに詳しいわけではないので、間違ってるかもですが。
— Ryo Maruyama (@h13i32maru) 2021年2月20日
という話もブログの最後に追記しておこう。
というわけでARCHITECTURE.mdについてのメモ書きでした。OSSのメンバーだったり、仕事でアーキテクチャを設計・実装する役割の人は書いてみるといいかもしれません。詳細度もあまり高くないのでそんなに時間がかからないと思います。その割にはメリットもありそうです（多分）。
