README.mdだけでなくARCHITECTURE.mdを書くべき理由を読む

GIGAZINEでも紹介されていた「アーキテクチャに関するドキュメント」について、仕事柄、必要かなと思ったので原文を読んでみる。

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

ARCHITECTURE.md

If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document next to README and CONTRIBUTING. Before going into the details of why and how, I want to emphasize that this is not another “docs are good, write more docs” advice.

10k-200k linesぐらいの規模のオープンソースプロジェクトを維持するのであれば、READMEやCONTRIBUTINGの次にARCHITECTUREのドキュメントを加えることをencourage（強く推奨）する。これは「ドキュメントを書くことは良いことなので、もっとドキュメントを書こう」と言ってるわけではない。

One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project. Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code.

core developerとoccasional contributorは、パッチを書くのにかかる差は2倍程度だが、どのコードに変更を加えるべきかを考えるのに10倍の時間がかかる。これはphysical architectureの知識の違いだ。

よくソフトウェアは人員を２倍にしても納期は半分にならない（むしろ長くなる）と言われますが、そうなる理由のひとつでもありますよね。

I find ARCHITECTURE file to be a low-effort high-leverage way to bridge this gap. As the name suggest, this file should describe the high-level architecture of the project.

ARCHITECTUREファイルは、このギャップを埋めるlow-effort high-leverageな方法だ。名前の通り、high-level architectureについて書かれている。

ここから先は実例を見てみたい。

rust-analyzer/rust-analyzer

On the highest level, rust-analyzer is a thing which accepts input source code from the client and produces a structured semantic model of the code. More specifically, input data consists of a set of test files ((PathBuf, String) pairs) and information about project structure, captured in the so called CrateGraph.

Bird's Eye View（俯瞰図）に「highest levelでは〜」と役割を簡潔に書き、次に入出力など順々に具体的に書いていく。

contributeする人にとっては自明のような気がするが、ポイントはここではなく、次に続くCode Mapだろう。

This section talks briefly about various important directories and data structures. Pay attention to the Architecture Invariant sections. They often talk about things which are deliberately absent in the source code. Note also which crates are API Boundaries. Remember, rules at the boundary are different.

Code Mapは各ディレクトリとデータ構造について書いている。Architecture invariant（不変）という注釈があるので注意してほしい。よくdeliberately absent（故意に欠けている）と言われることがある。APIのboundary（境界）があって、APIごとに境界が異なることも注意が必要だ。

意図的にやってる箇所については、意図を汲み取ってねという思いが滲み出ている。Githubに置かれているプロジェクトは、それ単体で動くソフトウェアではなく、ソフトウェアを支えるソフトウェアも多いから、様々なソフトウェアの開発スタイルがぶつかり合う。こういう記載が重要なのだろう。

Some of the components of this repository are generated through automatic processes. cargo xtask codegen runs all generation tasks. Generated code is generally committed to the git repository. There are tests to check that the generated code is fresh.

Cross-Cutting Concerns（横断的な関心事）という章があり、ここには一部のコードは自動生成であるとか、テストやエラー処理について書いている。

アーキテクチャについて明文化することで、プロジェクトに善意で貢献しようとする人のアイデアをスムーズに取り入れられるということが直接的な効果だろう。メンテナンスという長い長い旅を共にする仲間とは、コミュニケーションの規範を決めるcode of conductもいいが、やるべきことをスムーズに理解できるようなarchitecture.mdを整えることも効果があるかもしれない。