プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？

開発プロジェクトに新しく加わった時は、まずプロジェクトの理解が第一。しかし、全体像を把握できるようなドキュメントがなく、コードから断片的な情報をかき集めるしかない場合もあります。新参の開発者がスムーズにプロジェクトを理解できるよう、大規模なプロジェクトでは「プロジェクト全体のアーキテクチャ」を示した「ARCHITECTURE.md」を添えた方がよいと、エンジニアのAleksey Kladov氏が指摘しています。

ARCHITECTURE.md
https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html

Kladov氏はオープンソースプロジェクトの開発に携わる中で、「プロジェクトのアーキテクチャに対する知識量」によって開発スピードに大きな差が生じると気づいたとのこと。アーキテクチャに関する知識がない開発者にとって、大量のコードは「バラバラなデータ」と同じで読み解くのに時間を要します。しかし、「どこに何があるか」を示すアーキテクチャの知識があれば、もはやコードはバラバラなデータではなくなるとKladov氏は指摘。

プロジェクトに新しく加わった開発者が、コードのみを頼りにアーキテクチャを理解していくのは大変な作業。プロジェクトの概要が書かれた「README.md」や開発方針を示す「CONTRIBUTING.md」ファイルはよく添付されていますが、プロジェクト全体の理解を助ける性質の情報ではありません。Kladov氏はこうした背景を踏まえ、特にコードの総行数が1万行を超える大規模なプロジェクトにおいて、アーキテクチャを示す「ARCHITECTURE.md」を用意することの重要性を説いています。

ARCHITECTURE.mdの中心となるのは、「プロジェクトの全体像」とコードのつながりを表した「コードマップ」です。コードマップはそれぞれのコードが「どんな処理をするのか」「どこにあるのか」「どのように関わり合っているのか」を記述するにとどめ、詳細な説明については別のドキュメントにまとめるべきとKladov氏は指摘しています。

また、Kladov氏は「ARCHITECTURE.mdの内容はコードの変更に影響を受けない内容にすべき」ともコメント。数年単位の見直しで済むような低メンテナンスコストが重視されており、「ファイルやモジュールはリンクを作成せず、名称で検索できるようにする」といった具体的な方法も示されています。他にも「プロジェクトで不変とされる部分」「レイヤーやシステムの境界」といった、コードを読むだけではわかりにくい部分を明示することも大切だとKladov氏は語っています。

Kladov氏が中心メンバーとして開発に携わっている「rust-analyzer」には、実際に「architecture.md」が用意されています。

rust-analyzer/architecture.md at d7c99931d05e3723d878bea5dc26766791fa4e69 · rust-analyzer/rust-analyzer
https://github.com/rust-analyzer/rust-analyzer/blob/d7c99931d05e3723d878bea5dc26766791fa4e69/docs/dev/architecture.md

以下のようなプロジェクト全体の構造を表すイメージ図や……

コードマップが用意されており、コードに初めて触れる開発者の理解を助ける工夫がなされています。

なお、Kladov氏自身はドキュメント作成をおろそかにしがちで、プログラムの修正理由を「単純化した」で済ませてしまうような人物だとコメント。「ドキュメントはそれ自体がいいものなので、もっとドキュメントを書こう」という主張ではなく、あくまでアーキテクチャを記述する重要性を理解してほしいだけであると強調しています。