💡 主なポイント
- 表記の標準化：すべての図にわたって一貫した形状と記号を使用し、誤解を防ぐ。
- 命名規則：モデル内の明確さと検索可能性を確保するために、要素に対して厳格な命名規則を採用する。
- レイアウトの徹底：視覚的な流れを向上させ、認知負荷を軽減するために、均一な間隔と配置を維持する。
- 関係の明確化：システムの接続を正確に表現するために、線や矢印の明確なルールを定義する。
ソフトウェアアーキテクチャとシステム設計の分野において、図は普遍的な言語として機能する。抽象的な概念と具体的な実装の間の橋渡しを行う。しかし、内部的な整合性を欠いた図は、明確さではなく混乱の原因となる。整合性は単なる美的好みではなく、プロフェッショナルなモデリングにとって根本的な要件である。ステークホルダー、開発者、アーキテクトがモデルを検討する際、意味を迅速に抽出するために確立されたパターンに依存する。これらのパターンから逸脱すると、摩擦や潜在的な誤りが生じる。
このガイドは、統合モデル言語（UML）図における整合性を維持するための必須ルールを概説する。これらの原則は、視覚図を作成するためのツールにかかわらず適用可能である。目的は、直感的で、保守可能で、正確なドキュメントを作成することである。
1. 表記の標準 🎨
あらゆるプロフェッショナルな図の基盤は、モデリングコミュニティが定めた標準的な表記に従うことにある。ツールによってわずかな差異は存在するが、クラス、インターフェース、アクター、状態のための基本的な記号は一定である。これらの記号から逸脱すると、曖昧さが生じる。
クラス図の記号
クラス図を構築する際には、クラスに矩形の形状を厳密に適用する必要がある。ボックスは、クラス名、属性、操作の3つの明確なセクションに分けるべきである。名前は常に上部のセクションに配置する。属性と操作は、水平線で区切って下方にリストする。
- 公開メンバー：プラス記号（+）を接頭辞として使用する。
- 非公開メンバー：マイナス記号（-）を接頭辞として使用する。
- 保護メンバー：ハッシュ記号（#）を接頭辞として使用する。
- パッケージスコープ：チルダ記号（~）を接頭辞として使用する。
同じモデル内でこれらの規則を混在させてはならない。モデルで公開属性に+記号を使用する場合、すべてのクラスがこのルールに従わなければならない。可視性修飾子が一貫性を欠くと、アクセスレベルを一目で判断することが難しくなる。
シーケンス図のライフライン
シーケンス図において、オブジェクトや参加者の表現は一貫性を保たなければならない。ライフラインは、図の上部から下へ伸びる垂直の破線である。アクティベーションバーは、実行中にライフライン上に配置される細長い長方形である。すべてのアクティベーションバーの幅が同一であることを確認し、視覚的なリズムを維持する。
状態機械図
状態は、丸みを帯びた長方形で表現する。遷移は、開放矢印頭を持つ実線である。入力点と出力点は、特定の記号で明確にマークする（例：初期状態には塗りつぶされた円、最終状態には二重円）。同じ種類の状態に異なる形状を混在させると、視覚言語が破綻する。
2. 名前付けの規則 🏷️
UserUser」と名付ける一方、別のアーキテクトは「Person」を使用するかもしれません。ある人は「saveRecord()」を使用する一方、別の人は「persistData()」を好むかもしれません。このような違いは、読者が常に用語を翻訳しなければならないようにし、理解を遅らせるのです。
クラスおよびコンポーネントの名前付け
クラス名はPascalCaseの規則に従うべきです。これは各単語の最初の文字を大文字にするという意味です（例：CustomerOrder）。略語は単一の単語として扱うべきです（例：HTTPConnectionではなくHttpConnection）。これにより、クラス名が通常camelCaseを使用する変数名と明確に区別できることが保証されます。
属性およびメソッドの名前付け
属性およびメソッドはcamelCaseを使用すべきです。名前の最初の文字は小文字で、その後の単語は大文字にします（例：calculateTotal()）。この違いは、図をテキスト的に読みやすくするのに役立ちます。
| 要素の種類 | 規則 | 例 |
|---|---|---|
| クラス | PascalCase | PaymentGateway |
| 属性 | camelCase | 取引ID |
| メソッド | キャメルケース | processRefund() |
| インターフェース | Iで接頭辞が付く | IPaymentProcessor |
名前空間とパッケージ構造
モデルをパッケージや名前空間に整理する際、階層はシステムの論理的なドメインを反映するべきです。3レベルを超える深いネストを避けてください。パッケージ名には小文字を使用して、クラスと区別してください。例えば、com/company/projectは標準的ですが、com.Company.Projectパッケージかクラスを表しているのかが混乱を招く可能性があります。
3. レイアウトと余白 📏
ごちゃごちゃした図は失敗した図です。レイアウトの一貫性により、視聴者が情報を効率的にスキャンできるようになります。これには整列、余白、グループ化が含まれます。
グリッド整列
見えないグリッドを使用して要素を整列させます。クラスやコンポーネントを表す長方形は、水平または垂直に整列させるべきです。特定の関係の方向を示すために特に必要でない限り、要素を任意の角度に配置しないでください。関連するコンポーネントには、垂直スタックが一般的に推奨されます。
余白のルール
要素間の間隔を均一に保ちます。ある領域で2つのクラス間の距離が50ピクセルであれば、他の領域でも類似した距離にします。これにより、図がぎゅうぎゅうにならない「視覚的な呼吸空間」が生まれます。一貫した余白は、関連する機能のクラスタを識別するのにも役立ちます。
グループ化とフレーム
関連する図やコンポーネントをグループ化するためにフレームを使用します。フレームは特定のサブシステムに属するすべての要素を含むべきです。フレームの境界線は実線で、ラベルは左上隅に配置します。フレームが指定された範囲外の要素と重複しないように確認してください。
4. 関係線と矢印 ➡️
要素間の接続は、要素自体と同じくらい重要です。関係を誤って表現すると、システムの振る舞いについて誤った仮定を招く可能性があります。
関連と集約
関連と集約を明確に区別してください。関連は単純な線です。集約（部品が独立して存在できる「所有関係」）は、元の端に空のダイヤモンドを使用します。構成（部品が全体なしでは存在できない「所有関係」）は、塗りつぶされたダイヤモンドを使用します。異なる種類の関係に空のダイヤモンドと塗りつぶされたダイヤモンドを混在して使用しないでください。
依存関係線
依存関係は、開いた矢印頭を持つ破線で表現すべきです。これは、ある要素が別の要素に依存していることを示します。依存関係に実線を使用しないでください。実線はより強い構造的リンクを示すためです。矢印頭が依存される要素を向いていることを確認してください。
多様性
多様性の値（例：1、0..1、*）は、説明するクラスに最も近い線の端に配置してください。複数の多様性が表示される場合は、フォーマットを一貫させてください。必要なのに多様性を省略しないでください。暗黙的に示されている場所に多様性を追加しないでください。
5. 色と階層 🎨
色は意味を伝えるために控えめに使用すべきであり、装飾のために使うべきではない。色を多用すると階層が混乱する。すべてのクラスが異なる色になるなら、目が焦点を合わせる場所がなくなる。
標準の色パレット
最小限のパレットを採用する。例えば：
- 黒または濃い灰色： 標準的な要素。
- 青： インターフェースまたは抽象クラス。
- 緑： 実行中または動作中のプロセス。
- 赤： エラー状態または重大な警告。
色をランダムに適用してはならない。クラスが青色なら、モデル全体でインターフェースまたは抽象的概念を表している必要がある。状態が赤色なら、一貫してエラー状態を示している必要がある。
フォントの一貫性
モデル全体で1つの無衬线フォントを使用する。一般的な選択肢にはArial、Helvetica、Robotoがある。フォントサイズは読みやすく均一であるべきである。クラス名は太字にし、属性やメソッドは通常の太さにする。この視覚的な違いにより、図の内容を素早くスキャンできる。
6. ドキュメントとの整合性 📝
図の質は、それに付随するドキュメントの質に左右される。視覚モデルとテキスト説明の不整合は、技術的負債の主要な原因である。
バージョン管理
図のバージョン番号がシステムドキュメントのバージョンと一致していることを確認する。コードが変更された場合、図も更新されなければならない。削除された機能を示す図は誤解を招く。図の更新をコードレビューの一部とするルールを設ける。
文脈的なメモ
標準的な記号では表現できない複雑な論理を説明するためにメモを使用する。これらのメモは破線を使って特定の要素に接続する。メモのテキストは簡潔であることを確認する。図のボックス内に長い段落を記載すると可読性が低下する。メモが3行を超える場合は、別途仕様書を作成し、それを参照することを検討する。
7. レビューと保守 🔄
一貫性は一度きりの設定ではなく、継続的な実践である。システムの進化に伴い、基準が維持されているかを確認するために定期的なレビューが必要である。
自動チェック
可能な限り、モデルの一貫性を検証するツールを使用する。自動チェックにより、すべてのクラスが命名規則に従っているか、すべての関係に明確な多様性が定義されているかを確認できる。これにより、品質を維持するために必要な手作業を削減できる。
同僚レビュー
開発ワークフローに図のレビューを組み込む。同僚は定められたルールに従っているかを確認する。これにより、チーム全体でモデルに対する共有理解が生まれる。ルールが不明瞭な場合は、例外を許容するのではなく、スタイルガイドを更新する。
結論 🏁
UML図の一貫性を維持するには、規律と明確なルールセットが必要である。表記、命名、レイアウト、関係性、色を標準化することで、信頼できるドキュメントとして機能するモデルを作成できる。これらの図は、開発を加速させ、エラーを減らす共有資産となる。一貫性に投資した努力は、コミュニケーションの負担を軽減し、より高品質なシステム設計を実現する上で報酬をもたらす。
最初のスケッチから最終納品まで、これらのルールを厳格に適用する。プロフェッショナルな図は、プロフェッショナルなエンジニアリングプロセスの証である。