基本/詳細設計って呼び方やめませんか

[システムエンジニア Advent Calendar 2016](http://qiita.com/advent-calendar/2016/se) の 15 日目です。システムエンジニアなら避けては通れない設計について考えたことを書いてみようと思います。

# 設計ってむずかしい

システム開発の様々な局面で「設計ってむずかしいなあ」と思うことがあります。細かいところはシステムの規模や自分のポジションによって変わりますが、だいたい以下に挙げたようなことで困ることが多いです。

- 設計
  - なにを、どこまで、どんなフォーマットで書くといいんだろう？
  - 各ドキュメントはどうやって関連付けるといいんだろう？
  - 基本設計書と詳細設計書はなにが違う？
- 開発
  - なんでこういう設計になっているんだろう？
  - 設計されていない組み合わせのデータはどう処理すればいいんだろう？
- 試験
  - 試験データのパターンや量はどれくらい用意すればいいんだろう？
- 運用
  - 設計と実装が乖離していてなにが正しいのか分からない...
  - 仕様変更や機能追加はどの機能まで影響するんだろう？

そこで、「どうして設計がむずかしいと思うのか」について考えてみました。


# 基本/詳細設計とは

## V 字モデルで考える

そもそも設計とはどういう位置づけの作業なのでしょうか。システム開発の基本に立ち返って V 字開発モデルを眺めてみます。

![advent_001a.jpg](https://qiita-image-store.s3.amazonaws.com/0/6755/6d3d7aed-328f-e6c8-7432-6173d9da87b5.jpeg)

関連する前後の工程がよく分かりますね。

それぞれ前工程の成果物を基に、後工程の入力となるものを作ればよさそうです。裏を返すと、**基本設計書に単体試験の入力となるような内容は書かない** ということも言えそうです。

## ステークホルダーで考える

もう少し具体的にするために、各工程に関わるステークホルダーを追加してみましょう。

分業や多重請負について個人的に想うところは多々ありますが、この現実にどう立ち向かうのかという点がこの記事の目的なので、いまはその是非については触れません。

![advent_002a.jpg](https://qiita-image-store.s3.amazonaws.com/0/6755/dc8c5318-15c9-9d01-db01-f7993b5daf3d.jpeg)

各責任領域は体制や契約によって変わると思いますが、各工程には主担当がいるはずです。

そして、前工程の担当者は後工程で作られたものが正しいことをレビューする責任があるはずです。上記の場合、基本設計書をレビューするのはユーザなので、**基本設計書はユーザが理解できる内容でなければならない** ことが分かります。

## ロバストネス図で考える

それでは、どのような内容であればユーザが理解できるのでしょうか。ユーザとシステムの関わりはロバストネス図で分析することができます。

![](http://www.atmarkit.co.jp/fjava/devs/dstylefaq/uml/uml1_2/fig4.gif)
[＠IT：FAQ UML篇 UMLの9種類のダイアグラムとは？](http://www.atmarkit.co.jp/im/carc/serial/dstylefaq/uml/uml1_2/uml1_2.html)

ユーザはバウンダリを通じてシステムと関わることが分かります。「バウンダリ」とは「境界」のことなので、ユーザはシステム境界の外側を理解するということになります。これで、 **基本設計書はシステム境界の外側について書く** ということが分かりました。

一方で、 **詳細設計書はシステム境界の内側について書く** ということになりそうです。ロバストネス図に登場したコントロールやエンティティを、シーケンス図や ER 図に噛み砕いていけばいいんじゃないかな、ということが見えてきました。


# 基本・詳細 / 外部・内部

このように考えると、「基本」「詳細」ではなく「外部」「内部」と呼ぶ方が適切に思えますが、これらは相反する概念ではなく、直交する考え方のようです。

![](http://bluewatersoft.cocolog-nifty.com/blog/images/2009/05/19/program_design02_01.png)

- [[プログラム設計事始] 外部設計と概略設計: biac の それさえもおそらくは幸せな日々@nifty](http://bluewatersoft.cocolog-nifty.com/blog/2009/05/post-14a4.html)
- [[プログラム設計事始] 外部設計と内部設計の狭間: biac の それさえもおそらくは幸せな日々@nifty](http://bluewatersoft.cocolog-nifty.com/blog/2009/05/post-d8a6.html)

システムの規模が非常に大きい場合、外部設計、内部設計という括りだけでは対象が大き過ぎて全体を把握できないため、それぞれ基本設計、詳細設計に分ける、とあります。

|  | 外部設計 | 内部設計 |
|:-:|:-:|:-:|
| 基本設計 | 外部基本設計 | 内部基本設計 |
| 詳細設計 | 外部詳細設計 | 内部詳細設計 |

システムの規模がそこまで大きくない場合は、外部設計、内部設計だけでよさそうです。

ここまでで、「基本」「詳細」という呼び方ではいまいち分かりづらかった記述範囲がはっきりしてきたので、引き続き、これらの範囲内をどのように書くべきか考えてみます。


# 設計の 5W1H

よく分からないものについて考えるときに、取っ掛かりとして 5W1H で考えてみるのは定石です。言うまでもありませんが 5W1H とは

- WHEN (いつ)
- WHERE (どこで)
- WHO (だれが)
- WHAT (なにを)
- WHY (なぜ)
- HOW (どのように)

ですね。

このうち、WHEN と WHO はステークホルダーを追加した V 字モデルで明らかにしました。WHERE はあまり関係なさそうなので、残りの WHAT, WHY, HOW について考えてみましょう。

## 設計の WHAT

設計における WHAT とはどういうことでしょうか。

「なにを」設計するのかはもちろんですが、設計対象が「なにか」を記述することであると考えると、**設計という作業そのもの** と言えると思います。

設計対象が「なにか」を明らかにするには、設計対象の名前、振る舞いなどを記述すればよさそうです。

名前は、各ドキュメントで一意になる ID と論理名をペアで付与してやればよいでしょう。論理名だけでは、表記が揺れて各ドキュメントを関連付けられなくなる恐れがあります。

振る舞いは、図表やマトリクスなどを活用することで、入力、出力 (例外出力、エラー出力) の組み合わせを漏れなくダブりなく記述できますし、うまく作ればそのまま試験項目に流用することができると思います。


## 設計の WHY

同様に、設計における WHY とはどういうことでしょうか。

これは分かりやすいですね。「なぜ」そのように設計しているのか、背景や制約、方針を記述することであり、**設計の妥当性を判断する重要な情報** になります。

その設計対象が必要である理由を簡潔に記述し、なんらかの制約や設計判断があった場合は参考情報として書き留めておくと、なにかトラブルがあった際に役に立つはずです。

また、この情報によって、設計担当者の口頭による補足が必要なくなり、設計書レビューの速度と精度、および後工程の品質が向上すると思います。


## 設計の HOW

最後に、設計における HOW とはどういうことでしょうか。

WHAT で定めた設計対象の振る舞いを「どのように」実現するのか記述すると考えると、ロバストネスと図やシーケンス図、クラス図などを活用して、設計対象と関連する要素を記述すればよさそうです。

経験上、ここで注意しなければならないのは **後工程の HOW に踏み込まない** ということです。詳細設計書に具体的な処理手順や SQL を書く例をよく目にしますが、以下のような問題の原因となります。

- 責任領域があいまいになる
- 設計と実装が重複し、いずれ乖離する

「具体的な処理手順や SQL を書かないと細かい仕様が伝わらないのではないか」という主張をよく耳にしますが、WHAT で入出力の組み合わせを網羅的に定めていれば、その心配はないはずです。


# まとめ

以上のように考えた結果、冒頭に挙げた「どうして設計がむずかしいと思うのか」の本質的な原因は、各工程で設計すべき範囲、および記述すべき内容を明確に定義できていないことであると分かりました。

「基本」「詳細」という言葉は定義があいまいなので、例えばシステムの外部的な振る舞いを考えなければならない工程なのに、「こんな細かいことは詳細設計で考えればいいや」などと誤った判断をしてしまいます。

共通フレーム 2007 にも、同じ工程名でも実施内容が異なるため、同じ用語を使うようにと書かれています。

[
![advent_004.jpg](https://qiita-image-store.s3.amazonaws.com/0/6755/ad9c6c45-3d37-8d0f-cb62-f1d93bfa5dbe.jpeg)
ソフトウェア開発の標準プロセス(24ページ)
](https://www.ipa.go.jp/files/000031071.pdf "ソフトウェア開発の標準プロセス https://www.ipa.go.jp/files/000031071.pdf")

また、「設計書」という言葉には、どこか「組み立て説明書」のような印象があり、具体的な処理手順を書くものと誤解しやすくなっていると思います。

工程や成果物の名称はただの飾りであり、その内容が重要であることは言うまでもありませんが、少しでも誤解や認識齟齬を減らすために「基本設計」「詳細設計」をそれぞれ「外部設計」「内部設計」と呼び、各工程の成果物を「外部仕様書」「内部仕様書」と呼んでみてはどうかと考え、この記事を投稿しました。

![advent_003a.jpg](https://qiita-image-store.s3.amazonaws.com/0/6755/ff4638b2-d47d-bf3a-1ddb-ec0049d16366.jpeg)

まとめます。

- 各工程で設計すべき範囲を明確にしよう
    - ひとつの手段として、「基本設計」「詳細設計」ではなく、「外部設計」「内部設計」と呼んでみよう
    - ステークホルダーの責任領域を意識しよう
- 各工程で記述すべき内容を明確にしよう
    - ひとつの手段として、「設計書」ではなく、「仕様書」と呼んでみよう
    - WHAT, WHY, HOW を意識しよう

みなさんのご意見をお待ちしています。


# おまけ

設計に関するもうひとつの大きな問題は、「フォーマット」です。

図表を多く活用することから Microsoft Office 製品がよく使われていると思いますが、以下のような問題があります。

- バイナリファイルのためバージョン管理ツールとの相性が悪い
- 各ドキュメントを関連付ける機能が弱い
- 各ドキュメントを変更する場合の影響範囲が見えづらい
- 印刷がズレる
- 罫線や体裁など本質的でない問題に注意が発散する

これらを解決する万能ツールは今のところ存在していないと思いますが、やはり [Markdown による設計書](http://qiita.com/tenten0213/items/4099016c07ff99c93762#%E8%A8%AD%E8%A8%88%E6%9B%B8) が有望だと思います。

こちらについても、みなさんのご意見を頂戴できるとうれしいです。