開発者向けのソフトウェア設計書は必要か？

時々組織の内外で盛り上がるネタの一つに「設計書は必要なのか」談義がある。今回も後輩の一人から設計書不要論がぶつけられてきたので、現時点での個人的見解をまとめておくもの。個人的には、ソフトウェアの設計書は必須でもないし、開発戦略を練る段階で作成するかどうかを決めればいいと思っている。

議論の前提：仕様書と設計書

議論を簡単にするために、まず「仕様書」と「設計書」という言葉を再定義しておきたい。今回の整理は以下としている。

• 仕様書 … 開発者とユーザー(仕様決定者)が、ソフトウェアの振る舞いや動きに関してコミュニケーションするために必要な文書類のこと。
• 設計書 … 開発者どうしがソフトウェアを作成するにあたっての、構造や仕様についてコミュニケーションするために必要な文書類のこと。

要は今回議論しようとしている「設計書」は、ユーザー(仕様決定者)とは無関係なものであるという前提である。また、ここでは文書がフォーマルか、インフォーマルかどうかについては特に問わない。ホワイトボードに書かれた一時限りの図表であっても、テキストメモであっても、開発者どうしがコミュニケーションするために利用するのであれば今回は「設計書」として捉えたい。

また、今回は特にとりあげないけれども、「仕様書」は(体裁は別にして)基本的に必要なものだと考えている。ソフトウェアという(初回構築前には)可視性の低いものを扱うので、何らかの代替手段でソフトウェアの振る舞いを決定する必要はあるはず。なお、フォーマルなドキュメントで管理するのが難しければ、オペレーションマニュアル類と「仕様書」を合体させてしまうというのは時々やる打ち手だったりする。

設計書の目的ケースバイケース

冒頭にも書いたけれども、(開発者がコミュニケーションで使う類いの)設計書は必要であれば作ればいいし、必要でなければ作成する必要は無いと考えている。いちばんやっかいなのは過去のルールを盲目的に継続している場合だ。設計書を作ることは少なくともコストがかかる。何の目的で設計書を書くのか検討し、必要かどうかを確認すべきだろう。

古くからの習慣を打ち破るのは容易ではない。古い習慣に気づくのはそれに輪をかけて難しい。古い習慣を捨てるための最初の一歩は、自分のやり方が時代遅れだということに気づくことだ。これが最も難しい。同じくらい難しいのは、実際にそれを捨てることだ。メンタルモデルや思考パターンは、長年にわたり多大な代償を払って形成され、磨かれてきたものだ。だから軽々とは捨てられない。
アジャイルプラクティス 達人プログラマに学ぶ現場開発者の習慣 7.時が来たら習慣を捨てる(P36)

というわけで、ありそうな設計書の目的別に、ケースバイケースで考えてみたい。

顧客が設計書を求めている

これが最もよくあるタイプの壁なのだと思うけれども、これで思考停止するのは良くない。よく考えて、「本当に」設計書を作る必要があるのかと、「いつ」作るのかについては充分に考える余地がある。

• ビジネス契約上の問題で設計書を作成して納入する必要がある場合(例えば、ソフトウェアの完成前に中間支払いを受けるため等)であれば、真剣に代替手段を考えて良いと思う。その方面についてはあまり深くは知らないけれども、中間支払いの条件を見直すことは可能だ。それだけの目的で設計書を作成するのは馬鹿げている。
• ソフトウェアの完成後に設計書を納入する必要があるのであれば、設計書をソフトウェアの完成後に作成することも考えたほうがいい。事前に設計書を書くよりは、事後に設計書を書くほうが容易である。
• 設計書の事後作成で良いのであれば、完成したソフトウェアから設計資料を生成することも出来る(最近はあまりやったことが無いけれども)。可読性などには制約があるかもしれないが、「正確な設計書」を作成することもできる。

設計者とそれ以降の作業者が分かれている

これはSI屋や大規模開発ではよくあるケース。ただし小規模開発であったとしても、テストという観点が漏れがちなので注意が必要だと思う。

• サブコンストラクタ(オフショア含む)に実装を依頼するのであれば、基本的には設計書は必要だろう。ただしどこまで詳細に記載するかは、アーキテクチャなどにも依存するのでよく考えたほうがいいだろう。設計書以外の手段で作業依頼できるのであれば、もちろん設計書は必須ではない。
• 高度な品質が求められるソフトウェアでは、設計者とは異なるメンバーがテストを行うことによる品質向上が必要となる場合がある。これを実現するにはテストポイントを洗い出すためにある種の設計書が必要である。ただし、いまどきは設計実装レベルのバグ対策が出来る支援ツールも多いので、設計ドキュメントベースでの品質向上が本当に必要かはよく考えた方がいい(ツールでおさえられないポイントに限って文書化・テストすると考えたほうが合理的)。

設計書が他の利害関係者との合意形成に必要

例えば外部システムとのインターフェースなどについて、合意形成の証跡として設計書が必要な場合がある。この場合は(合意点に限っては)設計書は必要だろう。アジャイルと規律でも例として上がっている。ただ、必要なのは「合意形成の証跡」であるので、これを設計書と呼ぶ必然性はあまり無い。言った、言わないといった議論を防止できる程度のドキュメントがあれば充分だろう。

• 仕様書を使わないことのリスクが低く、使うことのリスクが高い場合には、仕様書を書くべきではない。そのよい例がGUI仕様書だ。高機能のGUI構築ツールを使っている場合には、仕様書を書かないで済ませるリスクが低くなる。イテレーションを何度も行なってGUIを構築する場合には、仕様書をイテレーションのつど書きなおすコストがかさむというリスクが高くなる。
• 仕様書を使うことのリスクが低く、使わないことのリスクが高い場合には、仕様書を書くべきである。そのよい例が、サプライチェーンのインターフェース規約に関する広範囲な利害関係者の交渉結果を記述した仕様書である。

アジャイルと規律 第5章 リスクを用いて俊敏性と規律のバランスをとる(P145)

有識者レビューによる品質担保が必要

古参の開発者や、ソフトウェアが対象とするドメインのエキスパートによるレビューが必要な場合に、設計書が有効なこともある(実装レベルでレビューするのは効率が悪いなど)。またドメインエキスパートがコードを読めない場合などもあるだろう。こういった場合は、特にレビューすべき対象について(レビューのための)ドキュメント化をすれば良いと思う。

• ソフトウェアの種類によってはレビューでの品質担保が不要というケースもあるのだろうけど、開発者の思い込み(思い違い)を除去するためにはやっぱり何らかのレビューは必要。
• ユーザが認識するレギュラーパターンの仕様については「設計書」ではなくて「仕様書」でおさえればいいのだと思うけれども、怖いのはイレギュラーケースの取扱いだったりする。イレギュラーケースの扱いを悩まなくて良いような種類のソフトウェアだったら、あまり考えなくて良いのかも。
• プログラムに「書かれていないこと」「抜けていること」を見つけ出すのを「コードレビュー」でやるのはやっぱり厳しい(単にわたしが老いたからなのかもしれないけど)。

ただ、この種のレビューは「品質担保に有効」であればやればよいと思うけれども、そうでなければ無駄なので削るべきだ。単にプログラムが読めない似非SEのための「仕様書」作成やレビューであれば、他のことで品質を上げたほうがいいと思う。

上記のいずれにも該当しない場合

設計書なんて作る必要ないんじゃない？

アジャイルプラクティス 達人プログラマに学ぶ現場開発者の習慣

アジャイルと規律 ～ソフトウエア開発を成功させる２つの鍵のバランス～

システム設計の謎を解く 強いSEになるための機能設計と入出力設計の極意

2012/8/9追記

保守はどうなの？というコメントをいただいたのでもう一つ記事を書いてみた。

• 保守開発者向けのソフトウェア設計書は必要か？ - 勘と経験と読経