外部仕様書(製品仕様書、基本仕様書）に書くべきことです。
外部設計の工程が2つまたは3つに分かれている場合もありますが、とりあえず1つになっている場合を仮定しています。
要件定義書があると仮定して、外部設計では以下を書くと思います。
- システム構成図
- ハードウェア仕様とソフトウェア仕様
- 外部に対するインタフェース、ユーザインタフェース
- 機能と処理の流れ
- 開発方針
会社によっては規格や規則など基準になっていて、何を書くべきかが決まっています。
最も書かなければならない製品のミッションステートメント
仕様書で最も書かなければならないのは「ミッションステートメント」と言えるような仕様です。
それがなければ他の項目をいくら一所懸命に書いたとしても「ぼんやりした仕様書」と言われてしまいます。
詳しくは以下をどうぞ。
>>> ITエンジニアが仕様書に最も書かなければならない1つのこと
また、ミッションステートメントを中心に考えた外部仕様書の書き方は以下です。
>>> 外部仕様書（製品仕様書、基本仕様書）の書き方 ミッションを中心に据えて
外部仕様書で書くべきこと
イト屋です。
外部仕様書で書くべきことをまとめてみます。
製品仕様書、基本仕様書などとも呼ばれる仕様書で、設計作業の最上位にある仕様書です。
要件定義書から「こういうものを作るよ」と宣言します。
プロジェクトによっては外部設計が2つや3つに分かれていることもありますし、逆に上流の要件定義の工程や下流の内部設計と同じになっていることもあるかと思います。
外部仕様の考え方
外部設計においては、要件定義から仕様に至った経緯、考え方をなるべく書きましょう。
数学の様に論理的に厳密である必要はありません。
「AAを満たすために、XXではなくてYYにした」
「YYにしたのは、AAのためだ」
「XXXの部分がYYYによって、AAA, BBB,CCC を実現することができる」
「拡張性を考慮しBBBを満たすようにXXXを採用する」
というような感じでOKだと思います。
こういう考え方を書いておくことによって、仕様書に説得力が出てきて他人が読める仕様書となります。考え方をちゃんと書いておくと、周りの人がよりよく仕様を理解し、内部設計、テストの工程が順調に進むようになります。
外部仕様書には、概ね以下の事を記述します。
- システム構成図
- ハードウェア仕様とソフトウェア仕様
- 機能と処理の流れ
- 外部に対するインタフェース、ユーザインタフェース
- 開発方針
システム構成図
ハードウェア的なシステム構成とソフトウェア的なシステム構成を書きます。
ハードウェア的なシステム構成は、サーバやスイッチをこう配置しますとかを書きます。
ソフトウェア的なシステム構成は、モジュールの一覧、プロセスの一覧みたいなものを書きます。
「モジュール」というのは、処理の塊で、プロジェクトによっては、「機能」「制御」などと呼ばれます。
図をかく
よっぽど単純なシステムでない限りは図をかいてどういうシステムであるかを示します。
お絵描きが嫌いな人も、全体のシステム構成図くらいはかきましょう。
後の章でも使えるような図であることが望ましいです。
同じシステムでも章ごとに違う図を用意するのは、書く方も読む方もつらいです。
ハードウェア仕様とソフトウェア仕様
ハードウェア仕様
ハードウェア仕様と言うのは、サーバであれば、CPU、メモリ、ディスク、ネットワークがどんなものを必要とするのかを書きます。
機器が固定であれば機種名（とか型名）、不特定な聞きを対象とするのであれば最低限動作するハードウェアを定義します。
おそらく執筆時点の、そのプロジェクトにとっての一般的なスペックのものを書くと思います。突出して性能がいいものを採用する場合は、その理由を書きましょう。
ソフトウェア仕様
使用するOS、ミドルウェア(webサーバ、SQLなど)、ブラウザなどを記述しておきます。
自分たちで作るものは内部設計書で記述するので、OSやミドルウェアの何を使っていくかということを記述します。
使うと決定しているOSSもここらで書いておきましょう。
外部に対するインタフェース、ユーザインタフェース
上流の人にとってはここが本論です。
外部インタフェース、ユーザインタフェースが、他製品や人とを繋ぐ入口です。
外部インタフェース
外部インタフェースといっても、まずどういうインタフェースなのかを明らかにしましょう。
- ライブラリを用いたAPIコール
- http/httpsのRESTインタフェース
- socketなどによる独自プロトコル
などがあります。
インタフェースごとに以下を記述します。
- 引数
- 返り値
- 繋ぐための作法（コールする順番）
- 最大接続数
- タイムアウト
- 異常時にやらなければならないこと
ここに書いていないことは、後で「それは仕様だー！」と言い張るのが困難になりますので、注意しましょう。
ユーザインタフェース
ユーザインタフェースを記述します。人間がどう関わっていくのかです。
GUIの場合は、画面一覧と画面遷移を示します。CLIであれば、そのコマンド仕様になります。
アクセスする方法、ユーザの権限などについても記述します。
ユーザインタフェースは、人が最も触れるので最も不良が顕在化しやすいところです。
書き始めるのが容易なところではありますが、難癖をつけるのも容易なところとなります。
苦労しますね。
機能と処理の流れ
システム構成図で出てきたモジュールを用いて処理の流れを書きます。
設計者や下流のエンジニアにとってはここが本論になります。
外部設計書のこの部分が後に続く内部設計への指針、憲法、命令となるように意識します。
なるべく、システム構成図そのもの、またはシステム構成図を拡張した図を使用して説明します。
細かくは内部設計ですが、大まかに以下は記述すると思います。
- モジュールをどう分けるか
- 各モジュールがどういう役割を担うか
- プロセスの構造
- 非同期処理
- 日時タスクがどう動くか
- 排他処理をどう使うか
モジュールをどう分けるか
モジュール一覧を書きます。
設計者が持てる能力と経験、センスを全て使ってどういうアーキテクチャにするかを考えます。
モジュールをどういう区分にするか、各モジュールがどう情報を受け渡すかを決めます。
何が自然か、作りやすいか、分かりやすいかをいろいろと悩みましょう。
各モジュールがどういう役割を担うか
どう分けるかと表裏一体ですが、各モジュールがどういう役割を担うかをモジュールごとに説明します。
プロセスの構造
プロセスの構造を書いておきましょう。
いくつかのモジュールをまとめて一つのプロセスのこともあれば、モジュールごとにプロセスを構成することも多いでしょう。
非同期処理
何かの処理を非同期にするつもりであれば書いておきます。
内部設計で検討するのは困難なものです。全体を見てこの処理を非同期にしておかないと、というのを先に考えておきます。
日時タスクがどう動くか
古いデータを消すとか、データベースのバックアップをとるとか、統計情報を収集するとか、1日に1回などの定期的に動く処理を設計します。
こういう処理を忘れないようにしておきましょう。工数をとるのを忘れることも多いのでちゃんとしておきましょう。
排他処理をどう使うか
多重にアクセスされる可能性のあるものについて排他を考えておきます。
所有するモジュールを決めて、モジュールが責任を持って排他して他モジュールは排他を気にしない、という設計をするなどを決めます。
開発方針
内部設計に対して方針だけは決めておきます。以下のようなことです。
- 性能に対する方針
- 障害に対する方針
- セキュリティに対する方針
- OSSに対する方針
- 開発環境
性能に対する方針
どうやって性能を達成するかです。ここまで来て書くことがあるのか？と思いますね。
非同期処理、排他処理をちゃんとできていればほぼ書くことはありません。
障害に対する方針
どのくらいの耐障害をもたせるかを書いておきます。
障害が起きたときをユーザや保守員にどうやって伝えるか、
回復は手動なのか、自動でできるようにするのかを記述します。
セキュリティに対する方針
httpであればhttpsを使うのかどうかです。
機器へのログイン、パスワードの管理、2段階認証の方針などを記述しておきます。
OSSに対する方針
OSSは、使うかどうか、修正するかどうか、です。
製品開発でOSSを修正するとなるとOSS専任の人を置く必要がでてきますよね。
開発環境
開発環境に何を使用するか、以下の一覧は入れておきましょう。
- プログラム言語
- コンパイラ、デバガ
- 単体テストフレームワーク（使うなら）
- svn, gitなどのバージョン管理システム
- Redmine, tracなどの問題点管理システム
まとめ
外部仕様で書くべきことをまとめました。
プロジェクトごとに若干異なるかと思いますので、規則、基準があればそちらに従ってください。
>>> 【ITエンジニア】工程ごとの分類
コメント