理想の設計書フォーマットを考える(Vol.16)

 2017.05.09  株式会社システムインテグレータ

コンセプト

本連載は、設計書ジェネレータ「SI Object Browser Designer(以下、OBDZ)」を使ってソフトウェアの設計書(仕様書、基本設計書、詳細設計書)を作る講座です。これまでは「設計で役立つOBDZ機能」をひととおりご紹介しました。今回はOBDZの思想的な話となりますが、「設計書とは?」という視点からOBDZを紹介したいと思います。

OBDZにご興味があればぜひ評価版をお申込みください。以下のURLよりお申込みいただくと、製品のダウンロードURLおよびログインに必要なアカウントを取得いただけます。
https://www.sint.co.jp/products/obdz/trial/trial.html

理想の設計書フォーマットとは?

さて、今回はスバリ「理想の設計書フォーマット」について考えてみたいと思います。おそらくこの業界で永遠に議論されるテーマではないかと思います。IT業界の設計書はWordやExcelというワープロソフト主流で作られてきた半面、会社や部署、案件ごとに設計書のフォーマットがバラバラであることが現実です。「設計品質が悪いほどトータルコストも肥大化する」とよく言われますが、所属する案件が変わるだけでも、新しい設計書フォーマットの読み方や作り方を覚えなければならないわけですから、明らかに品質にも悪影響を与えます。この課題を解決するために、時には会社単位で設計標準化プロジェクトを立ち上げて設計書テンプレートを作るようなこともされる企業も多くありますが、いざ現場で使おうとすると情報が足りない(あるいは過剰)とか、わかりにくいという理由で書き換えられてしまい、バラバラに戻ってしまうのが実情でしょう。

このような事実も踏まえれば、「理想の設計書フォーマットはない」というのが結論です。これも業界では定説とも言われますが、これで終わってしまうと身も蓋もないので、もう少し踏み込んで、「なぜ設計書フォーマットはバラバラになってしまうのか?」について考えてみたいと思います。その理由には大きく以下の3点があると考えています。

1.目的

一番の大きな要素はやはり「なんのためにその設計書を作るのか?」という点ではないでしょうか。設計書と一言に行っても、

・対象システムは汎用パッケージなのか、特定ユーザー向けの業務アプリケーションなのか?
・新規開発なのか、バージョンアップなのか?
・製造前に作るのか(ウォーターフォール型)、繰り返し(スパイラル型)で作るのか?
・設計書を渡す手はプログラマなのか、顧客なのか?
など、背景やシーンはバラバラです。これらのシーンにより当然求められる内容も大きく変わります。プログラマに向けであればプログラムにかかわる内部処理を詳しく書かなければならないですし、エンドユーザー向けであれば、外部仕様に重点を置くべきでしょう。

2.読み手の属性(人数・場所・知識等)

また、目的が「プログラマ向け」と一言で言っても、読み手となるプログラマが対象のシステムを長年携わっているベテランであれば、「○○画面にある○○機能を○○画面にも実装する」程度の記述で済むかもしれません。しかし、未経験のプログラマであれば、当然これだけの情報では理解できず、詳しい説明が必要になります。また、同じオフィス内に設計チームとプログラムチームがいて、人数も少なければ口頭のコミュニケーションで補足することができますが、人数が多くて口頭だけでは共有が難しくなります。また、拠点が離れていれば、コミュニケーション効率が落ちてしまいますので、できるだけ細かな事項も設計書内に記述しておく方がベターです。このように読み手の力量や人数、場所などにより設計書の粒度(レベル)も大きく変わります。 

3.他ドキュメントの存在

もう1つ忘れてはならないのは設計書以外のドキュメントのカバー度合でしょう。例えば、要件定義フェーズで業務フローが定義済なのか?基幹システムと連携するとすれば、基幹システムのドキュメントで取込インタフェースの仕様が記述されているのか?などです。もしこれらのドキュメントがなければ記載する必要がありますし、ドキュメントがあるのに設計書にも書くのは非効率です。

アプリケーション設計に関するお役立ち資料

lights.png

誰でも同じソースコードが書ける設計書って?
余談ですが、「誰が見ても完全に同じソースコードが書ける設計書こそ、理想の設計書フォーマットだ」と言う方がいました(だいぶ昔の話ですが)。COBOLやFORTLAN等の、基本的に処理が上から下に流れる「構造化プログラミング言語」が主流の時代は可能だったかもしれませんが、昨今ではJavaや.NETなどのオブジェクト指向言語、AjaxやHTML5などのフロントエンド言語の発達により非常に多様な実装が可能となりました。昨今では設計書だけで同一のソースコードを書かせることは非現実だと思っています。(100%同じソースコードが書けるドキュメントがあるとすれば、それはきっとソースコードでしょう!)
クラスの仕様やシグニチャ(引数仕様)、フロントエンドとサーバーサイドで設計書を分けるなどの方法である程度統一は可能ですが、内部のアルゴリズムや変数名などの細かな内容は、サンプルソースやコーディング規約などの補助ドキュメント、ソースレビューの作業で統一していくことが得策ではないかと思っています。
なお、OBDZではアルゴリズムなどの細かな記述機能はばっさりカットしています。この理由は次回ご説明したいと思います。

これらの要素によって必要なドキュメント体系や粒度が変わってくるものだと考えます。ドキュメント体系とは「画面レイアウト定義書」、「ロジック設計書」「クラス定義書」などの設計書の種類、粒度とは、「画面レイアウトイメージだけでなく、個々のテキストボックスなどの項目仕様も書くのか」や「画面単位で書くのか、さらにクラス単位に分けて書くのか」などです。

001.png

図1.求められる設計書の考え方

これらの関係を表したのが図1になります。少し大ざっぱですが、「目的」が「ドキュメント体系」、「読み手の属性」が「粒度」に大きく影響すると考え(相互にも影響を与えます)、この2つを掛け合わせた範囲に「その他ドキュメントのカバー範囲」を除いた部分が、求められる設計書像となります。

lights.png「基本(外部)設計書」と「詳細(内部)設計書」の住み分けについて
「基本設計書(外部設計書)」「詳細設計書(内部設計書)」をそれぞれどこまで書くべきか?という議論もありますが、これも絶対の正解はなく、今回挙げたような目的などの要素で正解が異なってくると思います。

また、図2のようにこれらの要素は案件によってバラバラのため、自社内であっても設計書の統一は難しいものと思います。しかし、要素の組み合わせごとにパターンを分類することで、複数パターンでの標準化パターン化なら可能そうに思えます。このように自社の案件パターンを整理し、パターンごとに標準化することが、理想の設計ではないでしょうか。

002.png

図2.求められる設計書は案件ごとにバラバラだが…

OBDZの設計書フォーマット

設計ツールOBDZはこのような思想から生み出したツールとなっており、「ドメイン」という機能で自社内に複数の設計書フォーマットを持つことができます。たとえば、「自社のパッケージ開発向け」や「EC案件向け」、「ERP案件向け」などのようにパターンを定義できます。ドメイン機能については第6回で詳しくご紹介しています。また、OBDZはExcelやWordテンプレートではなく、システムになりますので専用の入力画面(フレームワーク)により、属人化も強力に防止できます。
しかし、フレームワークが定まる反面、場合によっては従来の運用を変える必要がありますし、設計書フォーマットのカスタマイズ機能はあるものの作成できるドキュメント体系の大枠は定まっていますので、企業によってはまったく合わず、導入できない場合もあります。そのような意味では、OBDZも「ひとつの設計書の解(パターン)」でしかないということを留意する必要があります。
OBDZを導入する場合は、OBDZがどのような種類のドキュメントが作成でき、どのくらいの粒度ができるのかについて知ることが重要になります。こちらについては次回で説明したいと思います。

 

株式会社システムインテグレータ Object Browser事業本部 後迫

SI Object Browser Designer カタログ

RECENT POST「設計書の書き方講座」の最新記事


この記事が気に入ったらいいねしよう!
ブログ購読のお申込み

RANKING人気資料ランキング

RANKING人気記事ランキング

RECENT POST 最新記事

OBデザイナーで
生産性向上!