DDD / Documents and Diagrams

ドキュメントと図 (P.35) †

要約 †

(p35)

• ホワイトボードやスケッチブックに図を書くことなくソフトウェア設計について議論するのは困難なので，UML 図 (特にクラス図と相互作用図) を使う．
• UML 図では概念的な定義を伝えることはできないので，言葉で意味を肉付けする．
• UML は形式張らずに簡単に使うことができる．
• モデルや設計の全体を UML で記述するのは，複雑すぎたり「木を見て森を見ず」になったりトラブルの元．
• オブジェクトの振る舞いや制約を図で示すことは簡単ではないし，書くのも読むのも大変．

(P36)

• UML 図では，オブジェクトの振る舞いや責務は操作の名前や相互作用図で暗に示すことができるだけ．それらはテキストや会話に任せられる．
• ツールでコードから生成された UML 図はプログラムの異なったビューにすぎず，「モデル」としての意味は失われる．コミュニケーション用に別のモデルが必要となり逆効果．
• 図はコミュニケーションと説明のための手段で，重要な部分にフォーカスすれば設計の本質を理解しやすくなる．

(P37)

• 設計の詳細はコードから得られる．
  • よい実装は基礎となるモデルを透過的に表現する．
• 補足的な図とドキュメントはガイドになる．図の中にテキストで注釈するよりも，テキスト文書の中で簡単な図を使う．
• モデルとは図ではない
• 図の目的は，コミュニケーションの助けとなり，モデルを説明すること．コードは詳細設計のリポジトリ．

設計ドキュメントを書く †

(P37)

• 持続的で共有可能なドキュメントは必要．
• ドキュメントはコードやプロジェクトの進化から取り残されやすい．
• 具体的なドキュメントのセットは示さず (特別なものは Part IV で示す)，二つのガイドラインを提供する．

ドキュメントはコードと会話を補うものであるべき †

(P37)

• XP は設計ドキュメントを作るより，コードに語らせる．コードは嘘をつかないし，曖昧さがない．

(P38)

• ドキュメントや図，コード中のコメントさえも，コードと同期されなくなる．
• コードによるドキュメントだけでは UML を包括的に利用した場合と同じ．モデルを理解すべきなのは開発者だけではない．
• ドキュメントは，コードがうまくやれていることをやろうとしてはいけない．
• ドキュメントは，設計の意図を明確にすることができる．

ドキュメントは活用され，最新であるべき †

(P38)

• モデルをドキュメント化する時
  • 図は小さく，慎重に選択したモデルのサブセットをテキストで囲む．
  • クラスとその責務を言葉で定義し，意味的な文脈は自然言語で表現する．
  • 図はオブジェクトモデル中の概念を形式化し，(概念の数を) 減らす．
  • カジュアルに．手描きでもよい．

(P39)

• 設計ドキュメントの最大の価値は，モデルの概念を説明し，コードの詳細を案内する助けとなり，意図されたモデルの使い方に対する洞察を与えること．
• ドキュメントをプロジェクトの活動に関与させる．
• 誰も読んでいないか，それに従う理由がないドキュメントは目的を果たしていない．それを最新に維持するのは無駄な努力．

(P40)

• ドキュメントを最小限に維持し，コードや会話を補うことに集中することで，ドキュメントはプロジェクトとの関係を維持できる．

実行可能な基盤 †

(P40)

• 本書の多くは，MODEL-DRIVEN DESIGN により，コードで意味を伝える方法を議論する．コードの振る舞いは正しくても (現実であっても)，そこから得られるメッセージが正しいとは限らない．
  • メソッドの名前が曖昧，紛らわしい，(実装に追随してなくて) 古いなど．
  • テストによる表明は厳格でも，変数名によって語られるストーリーがそうとは限らない．
• この矛盾を取り除くのが宣言的な設計 (10 章)．
• 現在の標準的な技術を使ってコードの持つ振る舞い，意図，そしてメッセージを揃えるには，規律と (パート III で議論する) 設計についての特別な考え方が必要．

担当者のつぶやき †

• Repeat after me - Models are not necessarily documents, Models are not necessarily documents…
• ドメインモデルとドキュメント，コードの関係はこんな感じ？

• Evans が実際に携わったプロジェクトではどの程度の量・詳細度でドキュメントを作成していたのか，その時のプロジェクトはどの程度の規模だったのか知りたい．

みんなの突っ込み †

まとめ (議事録) †