残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門：プロジェクト成功確率向上の近道とは？（3）（2/3 ページ）

[寺田英雄，株式会社オープンストリーム CTO]

Design Docを書く

　いよいよ、Design Docを書いていきます。初めにやることは、システムに名前を付け、ドキュメントの冒頭の部分に署名し、そしてこのソフトウェアの目的やゴールを書くことです。

名前を付ける

　不思議なことに、良い名前を付けると設計がはかどります。そのシステムにふさわしい名前を付けて、表紙に記載しましょう。

目的やゴールを書く

　目的・ゴールの書き方の基本形は『このソフトウェアの目的は★★であり、◯◯を実現することがゴールである。』という定義文のスタイルです。何か誤解を生じる恐れがある場合は『なお、このソフトウェアには、××機能は含まない。』といった形で、除外されるものを明確にすることもあります。

　目的・ゴールは、できるだけ明確に書いておくことが重要です。この後の設計で迷ったときに、ここに立ち戻って判断することもあり、曖昧なままだと設計が迷走する原因になります。

背景を書く

　なぜこのようなソフトウェアを開発することになったのか、その動機や経緯などが分かると、あとで読む人がより深く設計の意図を理解できるので、可能なら書いておきましょう。

システム概要を書く

　ここからは具体的な設計内容です。文章の構成は『全体から部分へ』という順序で書くのが原則です。

　まずは全体の概要です。このシステム（モジュール）の最上位レベルの姿を記述しましょう。英語では『High-Level Architecture（ハイレベルアーキテクチャ）』と呼ばれます。システム構成図、クラス図などの図を添えると、より分かりやすくなります。

システム各部の設計を書く

　ソフトウェア各部の設計を項目別に記述していきます。その項目について、目的、データ構造、アルゴリズム、インタフェースなどを端的に記述します。必要なら疑似コードや各種のチャートなどを加えてもいいでしょう。また、どうしてそのような設計にしたのか、設計判断の理由を書き加えておくと別の読者の役に立ちます。

　なお、設計項目を決めていく際には、できるだけ一貫した方針で項目を決めるのが通例です。方針は基本的には以下の2つになることが多いと思います。

1. 機能で分ける
2. モジュール・画面などの物理的配置で分ける

　どちらが良いかはシステムの目的や設計の説明のしやすさなどから判断して決めてください。小・中規模のシステムでは機能で分けることが多いと思います。大規模なシステムでは、まず配置で分けてからそれぞれの機能を設計していく場合もあります。

その他の項目を書く

　テスト方針や、設計したライブラリやAPIなどの使用例、参考文献など、そのプロジェクトの目的に応じて必要だと思う項目を適宜考えて書き加えます。

リポジトリやクラウドに格納して共有する

　一通り仕上がったDesign Docは、チームで共有しましょう。他のメンバーにレビューを依頼してコメントをもらいましょう。複数の目でチェックすることで、ヌケモレや別の良いアイデアが見つかるかもしれません。

Design Docの書き方のポイント

結果だけではなく理由・背景を重視

　従来の『設計書』、設計の決定事項だけを記述することも多々あったと思いますが、Design Docでは、その決定に至った理由や背景（何のために、何を、なぜ、どのように）を重視して記述します。逆に、従来型の設計書に求められた細かなコードレベルのインタフェース仕様や、データベーステーブルの詳細定義などを記述することにはこだわりません。

ソースコードとペアで活用することを意識

　Design Docは、ソースコードとペアで活用することで最大の効果を発揮することを狙っています。従って、Design Docに書く内容がソースコードやコメントと同程度なら意味がありません。Design Docにはソースコードだけでは伝えにくい情報を書きましょう。

　情報の『詳細さの度合い』のことを情報の『粒度（りゅうど）』といいますが、粒度の小さな情報（＝詳細な情報）はソースコードとそのコメントで十分です。Design Docには、それよりも粒度の大きな情報、すなわち、設計の意図や背景、他のモジュールやシステムとの関係性などを書きましょう（図2）。

図2　Design Docにはソースコードを包括する情報や、背景情報などを書く

長文は必要ない

　Design Docは文学作品ではありません。項目をうまく区切って、テンポ良く読み書きできる文章を目指しましょう。長文も必要ないので、箇条書きや表などをうまく活用してシンプルで端的な文書作りを目指します。

　ただし、キーワードが並んでいるだけで、読んでも意味が分からないのはNGです。『読んで分かるけれども、無駄がない』文章が理想です。