プログラム設計書とは
プログラムを書くところからITエンジニアの世界に入ると、設計書というものの存在をどう捉えて良いかわからなくなるものです。特に独学でプログラムを学習した方にとってはイメージしにくいものとなるでしょう。プログラム設計書を知るにはシステムエンジニアの仕事内容から知る必要があります。
システムエンジニアは各種段階ごとに設計書を書き、プログラマーに実装してもらいテストを繰り返しつつプロダクトの完成を目指します。そしてシステムエンジニアには以下の文書を作成するフローがあります。
- 提案書
- 要件定義書
- 外部設計書
- 内部設計書
- プログラム設計書
- テスト仕様書
こうした書類の中の一部がプログラム設計書となります。
提案書
提案書はお客さんに「こういったシステムを導入したらどうでしょうか」と提案する書類で、システムを導入するための様々なメリットや導入費用や計画しているスケジュールなど様々なプロジェクト全体の要素が書かれることになります。
要件定義書
これは「こういったシステムを作ります」ということをお客さんと合意するための書類です。そのためIT分野に詳しくない方でもどういったシステムなのか理解できるような記述が求められます。また、この書類は提案書を元にして作成するものです。
外部設計書
大まかなプログラムの設計を記述した設計書です。お客さんに「こんな感じのシステムになります」というのが分かるようになっていて、主にユーザーを中心とした設計書となります。これも上流にあたる要件定義書を元にして書かれている書類です。
内部設計書
外部設計書を元にして書かれる内部設計書は、より詳細なプログラムの設計書です。どこからどんなデータを取り出し、どういった形でモジュールが連携しているのか等が書かれる設計書となります。
プログラム設計書
実際のプログラムをどう記述するかを書いた設計書です。具体的なモジュールの動作を決める箇所なので、プログラマはこの設計書を参照しながらプログラムを作成することになります。そして、もちろんこれも内部設計書を元にしています。
テスト仕様書
実装後のテストをどう行うかを記述した書類です。プログラム設計書通りに実装したプログラムに不具合が無いかどうかチェックするための仕様書となります。
このように、システムエンジニアは提案書から始まりテスト仕様書まで一貫した流れで各種書類を作成することになります。また、上流の書類は下流の書類を作成するための資料で、プログラム設計書はこの流れの一部に含まれています。
プログラム設計書は「内部設計書を元にした実装のための設計書」と言えるでしょう。簡単に言うなら「実装の設計書」です。どういった引数を持ちどういった機能を持つ関数を作るのか、といったコードに近い存在の設計書です。
プログラム設計書に書くべき項目
プログラム設計書は実装を指示する設計書で、この通りにコードを書けばプログラムが完成するというものです。といってもこの仕様は会社によって異なります。そのため具体的にはその会社の流儀に従わなければいけません。
仮に詳細なプログラム設計書を書かなければいけない会社の場合、書くべき項目はほぼコードと同じ意味の日本語全てとなります。それは以下のようなものです。
- 変数名やクラス名や関数名およびそれらの定義
- 定数名とその意味ないし数値のリスト
- 使用するライブラリ
- どこからデータを取ってくるか
- その他考えうる限りのプログラムに関する項目全て
こうなると直接プログラムを書いた方が速そうですが、プログラム設計書の一例としてはこうなります。そのため詳細なプログラム設計書を実直に作ろうとすると膨大な量のテキストとなるでしょう。
こうした問題は現場でも認識されていて、改善したいと考える方が居る一方、従来の習慣を守りたいという勢力も存在している状況です。
また、中にはこうした詳細すぎる設計書を嫌い、もっと簡便なプログラム設計書を書く企業もあります。コード内容は実装者に任せ、機能のみを羅列するといったプログラム設計書は柔軟で作りやすいものとなるでしょう。
ただ、これも設計者と実装者が互いに想定している能力の持ち主でなければ上手く行かないかもしれません。
どういった項目をプログラム設計書に含めるかは難しいところですが、実装者の能力が信頼できるものならモジュールの役割やデータの取得先などを記述するだけに留めると良いかもしれません。
また、実装者の能力が低く裁量を与えたくない場合は、できるだけぎちぎちに設計書を詰めて考えていくと良いでしょう。また、繰り返しになりますが会社の望むプログラム設計書を書くのが無難だったりもします。
プログラム設計書の書き方・例
プログラム設計書には各項目が色々とあります。例えば、定数リストを作成したり関数定義を行うといった具合です。EXCELによる定数リストの書き方は以下のようになります。なお書式にはJavaを使用しました。
EXCELによる定数リスト
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」についてのみなので注意しておきましょう。
プログラム設計書のおすすめテンプレート・ツール
プログラム設計書は会社によって扱いが異なるため最も相応しいテンプレートは会社にあるかもしれません。もし、会社がそれで作る事を望んでいるなら、その書式で書くしか無いでしょう。
また、こうした設計書を作るためのソフトウェアがいくつか存在しています。最早ソフトウェアを作るための設計書を作るためのソフトウェアという商売が成り立っている状況なのですが、ともかく存在しているのです。その中でも代表的なものをいくつか見てみましょう。
A HotDocument
実際に工数削減ということでプログラム設計書を撤廃しているところも存在しています。特に小さな案件や技術者集団にとって、設計書はあまり意味をもちません。むしろ業務を煩雑にする原因ともなり、設計書を書くことで能率が格段に落ちる現場もあるはずです。
ですが、大規模で数多くのエンジニアが関わっているプロジェクトでは設計書の重要性が増してきます。なぜなら誰も全貌を知らないわけですから、何かの指標が無ければ開発のしようがありません。
また、エンジニアの入れ替えがあるような場合でも設計書があると案件導入の助けになります。
一方、ソース内にJavadocのようなドキュメントを埋め込めばそれで事足りるという考え方もあります。ですが、それはプロジェクトに関わる全てのエンジニアがそのドキュメントを書くことができ、読むことができる場合にしか成立しないはずです。
もし読めないエンジニアが居た場合、やはり日本語で書かれたプログラム設計書が必要になるはずです。プログラム設計書は小さい規模の開発になるほど不要ですが、規模の大きな開発になるほど必要なものとなります。
プログラム設計書と詳細設計書の違い
設計書の読み方は会社によって異なります。詳細設計書という言葉でプログラム設計書を指すこともあれば内部設計書と読むこともあるぐらい用語が統一していません。
本来は内部設計と詳細設計では意味自体も異なるのですが、混同しているところもあるようです。そのため基本的には会社の先輩やプロジェクトに参加している同僚に、そこで使われている設計書の意味を尋ねてみましょう。
ですが、たいていプログラム設計書と詳細設計書は、同じ意味を指します。また、プログラム設計者や詳細設計書を外部設計書や要件定義書と混同するところは無いはずです。
取りあえずは「プログラム実装の前段階の設計書をプログラム設計書や詳細設計書と呼ぶ」という理解でいいでしょう。
プログラム設計は「現場のスキル」
プログラム設計スキルが役立つ企業
いかがでしたでしょうか。
プログラム設計は、実際にコーディングする際に必要な、フローです。要件を実装レベルに落とし込む、いわば現場監督のようなものと言えますね。
上流工程といったいわゆる「設計」のような外向きのスキルとは異なり、開発に携わる内向きのスキルでしょう。そのスキルは自社サービスを作るような企業で存分に発揮することができます。
自社サービスを作る企業で働くためには？
「自社サービスを開発する」というのは、エンジニアの目標・理想としてよく掲げられるものです。エンジニアなら「自分たちだけでサービスを作り上げたい」と思ったことが一度はありますよね。
自社のサービスを作っているWeb業界・ゲーム業界に行きたいと考えても、「自分のスキルが通用するのか不安」「給料が下がってしまいそう」と不安に思うことが少なくないですよね。
そんな人におすすめなのが、「TechStars Agent」です。
数年エンジニアを経験したサポーターが、あなたのスキルや技術、ポテンシャルを見抜き、希望の労働条件を最大限に叶えられる職場を一緒に探します。
- 希望年収以上の職場に出会える
- 技術に熟知したサポーターが一緒に職場を探してくれる
- 新しい技術・学びたい技術の職場に出会える
あなたもTechStars Agentで、理想の働き方を実現してみませんか？
