「Architecture.md (2021)」技術仕様書

 (matklad.github.io)
1 ポイント 投稿者 GN⁺ 2024-02-26 | 1件のコメント | WhatsAppで共有

ARCHITECTURE.md 作成の推奨

  • オープンソースプロジェクトのメンテナーに対して、README と CONTRIBUTING の横に ARCHITECTURE 文書を追加することを強く推奨している。
  • この文書はプロジェクトの高レベルなアーキテクチャを説明するもので、継続的に貢献する人が読むべきものなので、短く保つのが望ましい。
  • ARCHITECTURE 文書には頻繁に変更されない内容だけを含めるべきであり、コードとの同期を試みるよりも、年に数回見直すほうが望ましい。

文書の目的と重要性

  • プロジェクトの物理アーキテクチャに関する知識は、一般的なコントリビューターとコア開発者を分ける最大の違いである。
  • プロジェクトに不慣れな場合、パッチを書くのに2倍の時間がかかり、コードを変更すべき場所を把握するには10倍の時間がかかる。
  • ARCHITECTURE ファイルはこうしたギャップを埋める効果的な方法であり、プロジェクトの構造を見直す機会も提供する。

文書の構成

  • 問題に対する新しい視点からの概要で始め、モジュール間の関係を説明する詳細な コードマップ を提供すべきである。
  • 重要なファイル、モジュール、型を明示しつつ、直接リンクする代わりに名前で検索するよう促し、メンテナンス不要にするべきである。
  • アーキテクチャ上の不変条件を明示的に指摘し、レイヤー間の境界を示すべきである。

アーキテクチャ上の不変条件と境界

  • 重要な不変条件はしばしば何かの不在として表現され、コードを読むだけではそれを把握しにくい。
  • レイヤーやシステム間の境界は、システムの実装に関する情報を暗黙的に含んでおり、取り得る実装のすべてを制約する。

横断的関心事

  • コードマップを完成させた後、横断的関心事についての別セクションを追加すべきである。
  • ARCHITECTURE 文書の良い例として、rust-analyzer の architecture.md がある。

GN⁺の意見:

  • ARCHITECTURE 文書はプロジェクトの理解を助け、新しいコントリビューターがすばやくコードベースに慣れるうえで重要な役割を果たす。
  • この文書はプロジェクトの構造を明確にし、重要なアーキテクチャ原則と境界を強調することで、開発者がシステムをより深く理解する助けとなる。
  • オープンソースコミュニティで ARCHITECTURE 文書を採用することは、プロジェクトの持続的な成長と保守に貢献しうるものであり、開発者にとって非常に有益で興味深いアプローチである。

関連記事

1件のコメント

 
GN⁺ 2024-02-26
Hacker Newsの意見

  • オープンソースプロジェクトを管理していて、コード行数が 10k-200k の範囲なら、ARCHITECTURE ドキュメントを追加することを強く勧めます。

    • 発想は良いですが、リポジトリの規模に関係なく、README にアーキテクチャを含められると思います。たとえば、すべてのユーザーがワークフローを理解できるよう、メインの README に Mermaid のシーケンス図を意図的に配置しています。

  • このアプローチは、ad hoc な貢献者が多いオープンソースプロジェクトにとって、保守負担の少ないモデルとして優れています。専任エンジニアがいるプロジェクトでは ADRs を検討すべきです。こちらはより多くの保守を必要としますが、「なぜ」と「検討した代替案」を記録できるため、再構築時に非常に役立ちます。

  • 数年前、自分の大きなサイドプロジェクトの 1 つで似たようなことを試してみました:

    • 各ファイルの先頭に、別の ARCHITECTURE.md ファイルへのリンクツリーがありました。

  • どの IDE でも、標準的なディレクトリツリーとしてプロジェクトのフォルダ構造が左側に表示されます。依存関係グラフでプロジェクトを探索できる IDE はあるでしょうか?

  • ここで著者が書いていることを、一般的なソフトウェアプロジェクト全体に拡大適用する際には注意が必要です。文脈をあまり持たない多くの貢献者がいる大規模オープンソースプロジェクトでは、この種の文書を維持する価値があります。しかし、小規模な業務プロジェクトでは、これまで見た限り、開発者が書いた文書は結局どれもメンテナンスされなくなります。

  • 文書は短いほど、将来の変更によって無効化される可能性が低くなります。これが ARCHITECTURE 文書の主なルールです — 頻繁に変わる可能性が低いものだけを明記すること。コードと同期させようとしてはいけません。

    • インターフェースは変更されにくく、[より難しい!]（Parnas, システムをモジュールに分解するために使われる基準）。

  • どのプロジェクトでも、オンボーディング時にアーキテクチャ図とその構成要素の簡単な説明を見せています。

    • オープンソースでこれがいかに珍しいか、今では驚かされます。

  • これは非常に有用な実践です。多くのプロジェクトには、変更の大半が発生するいくつかの中核ファイル（あるいはパッケージ/モジュールなど）があります。新しい貢献者（または久しぶりに戻ってきた貢献者）がこれらを素早く把握できるようにすれば、プロジェクトに着手するまでの時間を大幅に短縮できます。

  • こうした小さな文書/コードによるダイアグラム標準は前から気に入っていました:

    • README 駆動開発
    • ARCHITECTURE.md
    • ADRs
    • arc42
    • C4
    • など。
    • 今では git リポジトリの /docs フォルダ内に Obsidian ボルトを置いています。
    • 誰かの標準を使う代わりに、Obsidian で自分の個人ノートを管理するように文書を整理し、リファクタリングしています。
    • GitHub(GFM) と Obsidian の両方で動作する共通の Markdown サブセットを使おうとしましたが、結局あきらめて、Obsidian の Markdown とその専用機能を使っています。
    • Obsidian には Mermaid と LaTeX が組み込まれており、PlantUML 用のプラグインもあります。
    • ビジュアルな図/ダイアグラム向けに Canvas、DrawIO、Excalidraw が組み込まれています。

  • 当時の議論:

    • Architecture.md - 2021年2月（153件のコメント）