アーキテクチャ図 は何をしますか?
図が理解されるのは、その内容が読み手の既知の知識に接続されたときです。シニア開発者は、トップレベルの流れと継ぎ目(シーム)を読み取ります。ブロックはブラックボックスであり、その設計パターン、責務、所有者、内部は非表示とします。あるブロックが別のブロックに継ぎ目を介して提供するものはインターフェースです。インターフェースには、操作(パラメータと戻り値の型)、エラー、やり取りされるデータ型(そのフィールド)、および実際に何がどのような形で渡されるかの例が含まれます。トランスポート(REST、OPC UA、プロセス起動)はインターフェースの属性であり、インターフェース自体を代替するものではありません。
描画する前にEXAMPLE.mdを読んでください。1つの変更を、両方の形式で完全に示しています。
手順
1. 読み手の言葉
新しい用語は何にも結びつきません。何よりも先に、読み手がすでに持っている言葉を収集します。この会話内のメッセージ、読み手が作成したドキュメント(プロジェクト指示書、アーキテクチャページ、用語集、命名規則表)、そして図と比較されるすべてのモデルから収集します。単語リストを作成します:事物、読み手の言葉、図を読む他の関係者の言葉、コード内の名前、図で使用する言葉。
- すべてのブロックとインターフェースには読み手の言葉をラベル付けし、コード名を横に併記します。
- 2つの言葉が衝突する場合、またはある言葉が誤った事物に使われている場合、1つを選び、単語リストで理由を説明し、もう一方の名前を一度だけ横に記します。
- 新しい言葉を作り出さないこと。コード内に名前のないインターフェースは、その両端の名前で呼びます(例:
Frontend -> Backend)。 - 読み手がすでに持っている図(自身の図、その階層と名前)から始め、新しいものをその中に配置します。
完了条件:図のすべてのラベルが単語リストに由来し、読み手にとって新しいすべての用語が、それが属する既知の単語とともに用語集に記載されていること。
2. 質問
読み手の質問を、1行に1つずつ記述します。質問がビューを決定します。
| 質問 | ビュー |
|---|---|
| 構成要素は何か、それぞれの責務は何か、誰が所有するか、誰が誰を呼ぶか? | 構成ブロック図 |
| 2つの構成要素を繋ぐインターフェースはどれか、そしてそれを横断するものは具体的に何か? | インターフェース、そのデータ型、すべての継ぎ目の例 |
| 重要なシナリオにおいて、何がどの順序で起こるか? | ランタイムビュー:1つのシーケンス |
| 各構成要素はどこで実行されるか? | すべてのブロックに host: を記載。ネットワークや信頼境界が問題となる場合はデプロイメントビュー |
| 変更によって何が変わるか、または2つの設計はどのように異なるか? | すべての状態を同じ形式で示し、その後差分を表示 |
完了条件:すべてのビューにその質問があり、その質問がビューのキャプションとしてその上に配置されていること。
3. カタログ
描画を開始する前に、ソースから4つのリストを作成します。
- ブロック:読み手の言葉とコード内の名前、ステレオタイプ、1文の責務、所有者、ホスト。
- インターフェース:継ぎ目ごとに1つ。提供者、消費者、すべての操作をシグネチャ
name(param: Type) -> Type、エラー、トランスポート。 - データ型:シグネチャで名前が挙げられたすべての型と、そのフィールド、単位、デフォルト値。
- 例:インターフェースごとに1つ。実際にやり取りされるメッセージ(コマンドラインとその出力、JSONボディ、テーブル行など)。実行結果、記録、フィクスチャ、またはデータから取得します。コードから組み立てた例は、その最初の行にその旨を明記します。
すべてのエントリには出典を明記します:コード参照 path:line、またはタグ(下記参照)。他の誰かが描いた状態、モデルファイル、またはスケッチは、そのままの形で、その独自の言葉で再現します。省略されている部分には [undefined] タグを付け、あなたが追加した部分は独自の状態として記録します。
完了条件:すべてのブロックに責務の一文があり、すべての継ぎ目にインターフェース(そのシグネチャはコードからコピーされるかタグ付き)があり、すべてのシグネチャ内の型にフィールドがあり、すべてのインターフェースに例があり、すべてのエントリに出典またはタグがあること。
4. 階層
ある状態のブロックはピアです。つまり、それぞれ独立してデプロイ、所有、または置換される単位であり、その数は5〜9個です。ファイル、関数、ブロック内部の手順は、そのブロックの内部と見なします。ズームは、さらに1階層下の図であり、質問の対象となっている1つのブロックに対して描画します。
完了条件:ある状態のブロックが別のブロックの内部に存在せず、すべてのズームに、そのズームを正当化する質問が示されていること。
5. 形式
- チャット形式:最大78桁。構成ブロック図(各エッジにインターフェース名と主なシグネチャ)、続いてテーブル形式のカタログ、コードブロック形式の例。単一の状態または小さな変更向け。
- キャンバス形式:必要な幅を持つテキスト図の静的HTMLページ。各エッジの横に完全なインターフェース、例、データ型とそのフィールドを表示。複数の状態、または3つ以上の継ぎ目を完全に表示する場合に使用。ページは、それと並置されたジェネレータスクリプトによって構築されます。チャットの回答はファイル名を指定し、比較結果が何を示すかを数文で説明し、未決定事項をリストアップします。
- C4形式:同一モデルをLikeC4で描画し、状態ごとにタブがあるページとして表示。クリックしてズームインできるボックス。テキスト図がプロトタイプとなります。まずそこで言葉、ブロック、インターフェース、例を確定させ、その後レンダリングします。他の人が開く結果向け。LIKEC4.mdを読んでください。
6. 描画
このフォルダ内の3つのファイルを使用して描画し、ボックスが揃い、行がキャンバス幅を超えないようにします。各ファイルのdocstringがマニュアルであり、実行するとデモが表示されます。
| ファイル | 機能 |
|---|---|
grid.py | Grid(コンパートメント、線、矢印を持つボックス)、sequence(ランタイムビュー)、table |
canvas.py | glance(すべての状態を1行で)、overview(状態を横に並べ、階層ごとに1行)、panel(1つの状態:ブロック、インターフェースと例、データ型) |
page.py | html_page:図を囲むページ。色とID間のリンクを含む |
likec4/ | C4形式用:template.c4、build.sh、tabs.js 付きのタブページ index.html、clicktest.py |
ページは、一目でわかる図から詳細へと進みます:概要、単語リスト、読み方ガイド、概要図、状態ごとのパネル、継ぎ目ごとの差分テーブル、未決定事項、用語集、出典。
7. チェック
- すべてのボックスはカタログのブロック、すべてのエッジはインターフェース、すべての型ボックスはデータ型です。図から意図的に省略されたエントリは、その目的があります。
- すべてのコード参照が解決可能であること:ファイルが存在し、その行に対象の名前が表示されること。
- 同じブロックはすべての状態で同じ位置にあること。ある状態に存在しないブロックは、点線のボックスで示します。
- ページ全体のスクリーンショットをタイルごとに確認:境界が合っている、切り取られていない、色が意味を持っている。
- 出典には、何を読んだか、どのコミットか、どの例が本物か、何を読まなかったかを明記します。
状態
状態とは、コードの現状、誰かが描いた目標、または提案です。状態を位置で比較します:glanceの同じ列、overviewの同じ行に同じブロックを配置し、2つの状態のギャップが互いを補完する場所を示します。
継ぎ目には、状態を表す文字と番号からなるID (I4) を持ちます。ある継ぎ目で定義されたインターフェースまたはデータ型は、他のすべての場所でそのIDで参照され、そのフィールドは一度だけ記述されます。
差分は、継ぎ目ごとに1行、状態ごとに1列のテーブルとして表示します。未決定事項は、質問、選択肢、決定者のテーブルです。
タグとステレオタイプ
| タグ | 意味 |
|---|---|
[code] | コード内に存在する。参照が横に記載される |
ソースタグ(例: [c4]) | ソースモデルによって示される。読み方ガイドでタグ名を明記 |
[proposed] | ここで提案されたもので、まだどこにも存在しない |
[new] [changed] [moved] | 変更による影響。現状と将来像のみがある場合に使用 |
[undefined] | 状態によって未定義とされている |
[?1] | 未決定事項。番号付きでリスト化 |
ステレオタイプは、ブロックが果たす設計パターンを示します:<<ui>>, <<client>>, <<gateway>>, <<facade>>, <<service>>, <<port>>, <<adapter>>, <<repository>>, <<external>>。コードがその役割を果たしている場合に使用します。ステレオタイプがないブロックは、間違ったステレオタイプがあるよりは優れています。ポートは、消費者が所有し、プロバイダが実装するインターフェースです:<<port>> はインターフェースに、<<adapter>> はそれを実装するブロックに付与します。ソースモデル独自の種類は、その記述通りに引用符付きで記述します。
説明手段
それぞれは、読み手が他の方法では尋ねるであろう事柄に答えることによってのみ、その場所を得ます。控えめに使用してください。
- 読み方ガイド:パネルの読み方とタグを示す1つの小さな図。
- コード参照:すべてのインターフェースとデータ型に付与し、読み手が確認できるようにします。
- 短いテキスト:状態の上に1段落で、その状態で見るべき1つのこと。インターフェースボックス内に、読み手が「なぜ」と尋ねるであろう場所への注釈。
- 用語集:単語リストでカバーされていない用語を、1行に1つずつ。
- 色:タグ、ID、およびすべての状態で共通する1つか2つの
key名にのみ使用。色は、状態が共有するものと異なるものを示します。それ以外には色を使いません。
文章は会話の言語で記述します。コードやソースモデルからの名前はそのまま使用します。