プログラム設計書とは？｜各設計書の違いと書き方

プログラムを書くところからITエンジニアの世界に入ると、設計書というものの存在をどう捉えて良いかわからなくなるものです。特に独学でプログラムを学習した方にとっては、イメージしにくいものとなるでしょう。プログラム設計書を知るには、システムエンジニアの仕事内容から知る必要があります。

システムエンジニアは各種段階ごとに設計書を書き、プログラマーに実装してもらいテストを繰り返しつつプロダクトの完成を目指します。そしてシステムエンジニアには、以下の文書を作成するフローがあります。

• 提案書
• 要件定義書
• 外部設計書
• 内部設計書
• プログラム設計書
• テスト仕様書

こうした書類の中の一部がプログラム設計書となります。

提案書は、お客さんに「こういったシステムを導入したらどうでしょうか」と提案する書類です。システムを導入するための様々なメリットや、導入費用や計画しているスケジュールなど、様々なプロジェクト全体の要素が書かれるものです。

要件定義書は、「こういったシステムを作ります」ということをお客さんと合意するための書類です。そのためIT分野に詳しくない方でも、どういったシステムなのか理解できるような記述が求められます。また、この書類は提案書を元にして作成します。

大まかなプログラムの設計を記述した設計書です。クライアントに「こんな感じのシステムになります」と説明する書類で、主にユーザーを中心とした設計書となります。これも上流にあたる要件定義書を元にして書かれている書類です。

外部設計書を元にして書かれる内部設計書は、より詳細なプログラムの設計書です。どこからどんなデータを取り出し、どういった形でモジュールが連携しているのか等を記載する設計書です。

実際のプログラムをどう記述するかを書いた設計書です。具体的なモジュールの動作を決める箇所なので、プログラマはこの設計書を参照しながらプログラムを作成することになります。そして、もちろんこれも内部設計書を元にしています。

実装後のテストをどう行うかを記述した書類です。プログラム設計書通りに実装したプログラムに不具合が無いかどうか、チェックするための仕様書となります。

このように、システムエンジニアは提案書から始まり、テスト仕様書まで一貫した流れで各種書類を作成することになります。また、上流の書類は下流の書類を作成するための資料で、プログラム設計書はこの流れの一部に含まれています。

プログラム設計書は、「内部設計書を元にした実装のための設計書」と言えるでしょう。簡単に言うなら「実装の設計書」です。どういった引数を持ち、どういった機能を持つ関数を作るのか、といったコードに近い存在の設計書です。

プログラム設計書は実装を指示する設計書で、この通りにコードを書けばプログラムが完成するというものです。とは言え、この仕様は会社によって異なります。そのため、具体的にはその会社の流儀に従わなければいけません。

仮に、詳細なプログラム設計書を書かなければいけない会社の場合、書くべき項目はほぼコードと同じ意味の日本語全てとなります。それは以下のようなものです。

• 変数名やクラス名や関数名およびそれらの定義
• 定数名とその意味ないし数値のリスト
• 使用するライブラリ
• どこからデータを取ってくるか
• その他考えうる限りのプログラムに関する項目全て

こうなると直接プログラムを書いた方が速そうですが、プログラム設計書の一例としてはこうなります。そのため、詳細なプログラム設計書を実直に作ろうとすると、膨大な量のテキストとなるでしょう。

こうした問題は現場でも認識されていて、改善したいと考える方が居る一方、従来の習慣を守りたいという勢力も存在している状況です。

また、中にはこうした詳細すぎる設計書を嫌い、もっと簡便なプログラム設計書を書く企業もあります。コード内容は実装者に任せ、機能のみを羅列するといったプログラム設計書は、柔軟で作りやすいものとなるでしょう。

ただこれも、設計者と実装者が互いに想定している能力の持ち主でなければ上手く行かないかもしれません。

どういった項目をプログラム設計書に含めるかは難しいところですが、実装者の能力が信頼できるものなら、モジュールの役割やデータの取得先などを記述するだけに留めると良いかもしれません。

また、実装者の能力が低く裁量を与えたくない場合は、できるだけ設計書を詰めて考えていくと良いでしょう。また、繰り返しになりますが、会社の望むプログラム設計書を書くのが無難である可能性もあります。

プログラム設計書には様々な項目があります。例えば、定数リストを作成したり関数定義を行うといった具合です。EXCELによる定数リストの書き方は、以下のようになります。なお、書式にはJavaを使用しました。

No｜名称｜値｜型｜クラス名｜ファイル名｜書式｜説明

1｜HOGE_HOGE｜100 ｜int｜Hoge｜Hoge.Java static final int HOGE_HOGE｜ほげ番号
2｜HOGEN_HOGEN｜1.14142｜double｜Hoge.Java static final double｜ HOGEN_HOGEN｜ルート2の代わり

といった具合です。この書き方はやや冗長すぎる例ですが、名称と値と説明があれば十分に定数リストとして機能するでしょう。ファイル数が膨大ならファイル名も書いた方が良いですし、クラス名を入れるべき場合もあるでしょう。また、会社が求めるなら冗長な書式も書くことになるかもしれません。

関数定義をする際には「書式・機能・引数・戻り値」などを書き、例は以下のようになります。

• 書式：boolean check_add_minus(int a,int b)
• 機能：引数を加算した結果がマイナスかどうかを真偽値で返す。
• 引数int aの意味：第一項
• 引数int bの意味：第二項
• 戻り値：true：マイナスである
• 戻り値：false：マイナスではない

設計書を見るだけでもプログラムが書けるよう心がけましょう。プログラムを日本語化したものがプログラム設計書と言えます。

• 書式：boolean check_add_minus(int a,int b)
• 機能：引数のint aとint bを演算してその結果がマイナスかどうかを返り値で返す関数です。
• 引数int aの意味：変数1
• 引数int bの意味：変数2
• 戻り値：true：マイナスのときに返します。
• 戻り値：false：マイナスではないときに返します。

この場合作ってもらいたいものは同じなのですが、表現が異なるため意味が伝わり辛いと思われるかもしれません。例えば、機能の項目において「加算」ではなく「演算」という言葉を用いているため、プログラマはどういった処理内容を作るべきか分からなくなってしまいます。

また、引数の説明においても「変数1」というのは理解し難い表現です。さらに全体的に文章が冗長である点も、設計書の内容を分かり辛くしています。

このように、日本語という日常言語でプログラムを表現する場合には、表現に気をつけなければいけません。プログラム設計書を受け取ったプログラマが、コードを書きやすい設計を心がけましょう。つまり、他人が一目見ただけで、理解できるような設計書を書くようにしなければいけないのです。

では、実際に簡単なプログラム設計書を書いてみましょう。ここでは「本棚に引数分の本を収容できるかどうかを返す関数」を定義してみます。まずは、「本棚に収容できる本の上限数」を定数として定義するところから始めましょう。

No｜名称｜値｜型｜クラス名｜ファイル名｜書式｜説明

1｜BOOK_LIMIT｜30｜int｜book｜testdayo.Java static final int BOOK_LIMIT｜収容できる本数の上限

• 書式：boolean check_book_limit(int storage)
• 機能：収納したい本の数（storage）が収納の上限数（BOOK_LIMIT）内に収まるかを真偽値で返す
• 引数int strageの意味：収納したい本の数
• 戻り値：true：収納できる
• 戻り値：false：収納数が上限を超えるため収納できない

メインから呼び出していて「int testinput」の数値によって実行結果が異なるようになっています。ここで取り扱っているプログラム設計書に相当するのは「class book」についてのみなので、注意しておきましょう。

プログラム設計書は会社によって扱いが異なるため、相応しいテンプレートは会社にあるかもしれません。もし、会社がそれで作る事を希望しているなら、その書式で書くしか無いでしょう。

また、こうした設計書を作るためのソフトウェアがいくつか存在します。

実際に工数削減ということで、プログラム設計書を撤廃しているところも存在しています。特に小さな案件や技術者集団にとって、設計書はあまり意味をもちません。むしろ業務を煩雑にする原因ともなり、設計書を書くことで能率が格段に落ちる現場もあるはずです。

ですが、大規模で数多くのエンジニアが関わっているプロジェクトでは、設計書の重要性が増してきます。なぜなら誰も全貌を知らないわけですから、何かの指標が無ければ開発のしようがありません。

また、エンジニアの入れ替えがあるような場合でも設計書があると案件導入の助けになります。

一方、ソース内にJavadocのようなドキュメントを埋め込めば、それで事足りるという考え方もあります。ですが、それはプロジェクトに関わる全てのエンジニアが、そのドキュメントを書くことができ、読むことができる場合にしか成立しないはずです。

もし読めないエンジニアが居た場合、やはり日本語で書かれたプログラム設計書が必要になるはずです。プログラム設計書は小さい規模の開発になるほど不要ですが、規模の大きな開発になるほど必要なものとなります。

設計書の読み方は会社によって異なります。詳細設計書という言葉でプログラム設計書を指すこともあれば、内部設計書と読むこともあります。

本来は内部設計と詳細設計では意味自体も異なるのですが、混同しているところもあるようです。そのため、基本的には会社の先輩やプロジェクトに参加している同僚に、使われている設計書の意味を尋ねてみましょう。

いかがでしたか。

プログラム設計は、実際にコーディングする際に必要なフローです。要件を実装レベルに落とし込む、いわば現場監督のようなものと言えます。

上流工程と言った、いわゆる「設計」のような外向きのスキルとは異なり、開発に携わる内向きのスキルでしょう。自社サービスを作るような企業で存分に発揮することができます。