ソフトウエア設計書に書きたい項目<span class="fz-18px"> －ソフトウエア設計シリーズ「破」⑦</span>

ソフトウエア設計シリーズは設計と文書化をテーマとし、設計を文書に表現する技術を考察している。
本記事では、ソフトウエア設計書に書きたい／記載すべき重要な項目を、レビュー観点の形式で示す。

ソフトウエア設計シリーズ「破」⑦		ソフトウエア設計書に書きたい項目	松浦公政	2024年
対象読者	どのようなソフトウエア設計書を作るべきか検討しているＩＴ技術者・システムエンジニア
	ソフトウエア設計書のレビュー項目を検討している品質管理者・ＩＴ技術者
	分かりやすい技術文書を模索している方

記事の音声解説付き（下のプレイボタンで解説開始）

ソフトウエア開発の設計レビュ―観点
設計レビューの確認項目例

ソフトウエア開発の設計レビュ―観点

ソフトウエア設計書は、将来そのソフトウエアの開発を引き継ぐ技術者の視点こそ重要だ

ソフトウエア開発で作る設計書は、前工程の要件決定者と、次工程の実装担当者（プログラマ）の間にあって、実現したいモノを段階的に詳細化・具体化する橋渡しの役割を持つ。
またソフトウエアには寿命があり、その存命中に機能追加したり、変更したりを想定すると、設計書は将来そのソフトウエアに関わる人々が最も頼りにする貴重な情報源となる。
以上を踏まえると、設計書の利用者は次の三者に大別できる。

設計書の利用者	利用方法
要件決定者（主に顧客）	顧客の要求真意を設計者が言語化・図化して可視化した文書
実装担当者（主にプログラマ）	設計内容をコンピュータが理解できる言語に変換する際の情報源
将来の設計者・実装担当者（当該製品の開発を引き継ぐ技術者）	製品を改善・保守する際の方針・方法を示唆する貴重な情報源

上述の三者を設計書の読者と想定し、設計書に「重要な／記載が望ましい」要点を、抽象的な「レビュー観点」の形式で示す。

分類	レビュー観点	観点を設ける目的（確認したい要点）
外部整合性	上位文書との整合性	求められた／期待された要求・要件を漏らしてないか。
外部整合性	外部の機能・システムとのインターフェース整合性	関係する／影響する外部と適切に連携するか。
設計品質	デ―タ（変数・DB ・ファイルなど）設計の妥当性	多様な技術者が理解でき、納得できる構造・作り方か。
	構造設計の妥当性	多様な技術者が理解でき、納得できる構造・作り方か。
	状態設計の妥当性（主にイべント駆動型プ口グラム）	起こり得る状況の網羅に考慮不足・想定漏れがないか。
	動的連携（シ一ケンス）設計の妥当性
	詳細設計の妥当性
非機能要件	性能設計の妥当性	実用時に起こり得る問題・課題の考慮に不足がないか。
	セキュリテイ設計の妥当性
	互換設計の妥当性
	運用設計の妥当性
文書品質	名称設計の妥当性	多様な関係者が理解でき、読者それぞれが必要なアクションを始められるか。
	設計の理解促進性
	記述作法の合理性
	記載具備の充足性

設計レビューの確認項目例

設計レビューの確認項目は、開発組織のＤＮＡとして維持管理すべき財産になる

前述の抽象的なレビュー観点に対する具体的な確認項目例を示す
なお［入力→処理→出力］のセットに名前が付いた単位を「機能」と記している

分類	観点	確認項目例
外部整合性	上位文書との整合性	トレーサビリテイ（上位文書が要求する役割・機能を漏れなく展開）を精査したか。
		外部機能との協調・協同・連携で上位文書の要求機能を実現する見通しを検証したか。
		上位文書と整合する設計方針（例：設計思想／分割指針／達成目標など）を明示したか。
		上位文書の意図と整合するエラー判定指針／異常処理方針を明示したか。
	外部の機能・システムとのインタ―フエース整合性	入力とする外部データ（引数・大域データ・フアイル）の想定に不足がないか。
		入力デ一タの値域（取リ得る値の範囲）定義に暖昧さがないか確認したか。
		当該設計対象が出力するデータの値域（取り得る値の範囲）を明示してあるか。
		口グ出力方針と照らして口グ出力デ一タの不足がないか。
設計品質	デ―タ（変数・DB ・ファイルなど）設計の妥当性	設計したデータの目的・意図を明示してあるか。
		当該設計対象の規模・複雑度に対し、設計したデ一タ項目の件数（過多／過少）は妥当か。
		構造体型データ（例：DB のテ一ブル）を構成する要素デ一タ数（過多／過少）は妥当か。
		構造体型データを構成する要素データは、親構造の構成要素として親和性があるか。
		DBのテープルの正規化水準（別テープルとのデ一タ重複による冗長性）は妥当か。
		デ―タの値域（取り得る値の範囲）を一意（例：重さと高さなど別軸を混在させない）に設計したか。
	構造設計の妥当性	当該設計対象に想定される規模と比ペ、静的な階層構造（階層数・層の秩序）が妥当か。
		当該設計対象が属する階層の抽象度と比べ、機能の粒度（大雑把／過精細）が妥当か。
		当該設計対象を分割する場合、サブ機能群を一覧表（または箇条書き）に整理しているか。
		分割設計した全ての機能群にっいて、役割・入出力を明記してあるか。
		分割設計した機能の役割分担に暖昧さ（誰の役割か不明瞭など）が残ってないか。
	状態設計の妥当性（主にイべント駆動型プ口グラム）	状態数に不足がないか。
		事象の想定漏れがないか。
		内部状態値と事象発生のマトリクス検討に抜け漏れがないか。
		状態・事象を階層化する要否を検討したか。
		状態遷移を伴う事象発生のシナリオ検討に不足がないか。
	動的連携（シ一ケンス）設計の妥当性	事象発生に伴う動的連携で、登場する役割（口ール）の想定漏れはないか。
		事象発生に伴う動的連携に登場する役割（口ール）間で、デ一タ受渡しの順序性は妥当か。
		事象発生に伴う動的連携に登場する役割（口一ル）間で、受渡すデータの内容は妥当か。
		事象発生に伴う動的連携で、発生する事象の想定漏れはないか。
		複数事象発生の順番変更に伴う動的連携（シーケンス）のシナリオ抽出に検討不足がないか。
	詳細設計の妥当性	入力データの異常値を考慮したケースを設計してあるか。
		条件分岐判定の設計は、入力データの組合せの全パターンを網羅しているか。
		異常検出時／異常発生時の処理設計に考慮漏れがないか。
		異常検出時／異常発生時の処理設計は安全サイドに寄せているか。
		異常な状況で機能が実行された場合の想定範囲は妥当か。
		初期化不要なデータと判断している場合、判断理由は妥当か。
		処理の複雑度が高過ぎないか。（目安：サイク口マテイック複雑度＜10)
非機能要件	性能設計の妥当性	当該設計対象が持つ性能への影響の大きさを確認したか。
	性能設計の妥当性	当該設計対象が性能に大きく影響する場合、性能要件の充足性を考慮した設計か。
	セキュリテイ設計の妥当性	当該設計対象が持っセキュリテイ（潜在的な場合を含む）への影響の大きさを確認したか。
	セキュリテイ設計の妥当性	当該設計対象がセキュリテイに影響する場合、セキュリテイ要件の充足性を考慮した設計か。
	互換設計の妥当性	当該設計対象が下位層（ミドルウエア等）との互換性の影響を受けるかを確認したか。
	互換設計の妥当性	当該設計対象が下位層との互換性の影響を受ける場合、互換性を考慮した設計か。
	運用設計の妥当性	他のプ口ジエクトと比較してサービスレペルの合意項目に過不足がないか確認したか。
文書品質	名称設計の妥当性	機能の「出力」ゃ「動作」をイメージできる機能名称で命名したか。
		当該設計対象が属する階層の抽象度と比べ、機能名称の抽象度が遜色ないか。
		機能名称と記述内容（中身）に垂離がないか。
		データの目的をイメ一ジできるデ一タ名称で命名したか。
		ファイル（例：帳票）の目的をイメ一ジできるファイル名称で命名したか。
		図表がある場合、図（表）の名称と、図（表）が表す内容に乖離がないか。
		呼出名称、引数名称、データ名称が命名規則に準拠するか。
		定義済のシンボルを利用する場合、シンボルを間違えて使ってないか。
	設計の理解促進性	説明が結論先取型（「結論は○○○。理由は□□□だから」という順序性を維持している）か
		当該設計対象と外部との関係性（例：情報交換、連動）の図示要否の検討不足がないか。
		当該設計対象を内部で分割する場合、関係性（例：構造）の図示要否の検討不足がないか。
		当該設計対象の状態を設計する場合、図示（例：状態遷移図）の図示要否の検討不足がないか。
		当該設計対象の意匠を設計する場合、図示（例：画面配置図）要否の検討不足がないか。
		ニ次元の表に整理できる設計情報を、文章（箇条書き含む）で済ませてないか。
	記述作法の合理性	目次がある場合、章構成が、抽象度高→抽象度中→具体化の流れを持つか。
		想定読者に馴染みがない専門用語／業務特有の用語を使う場合、用語解説があるか。
		用語を一般的な解釈（辞書の上位に表示）と異なる／独自の意味で使う場合、用語解説があるか。
		記述の揺れ（詳細過ぎる／簡素過ぎるの混在）の程度は合理的と言える範囲内か。
		当該機能の利用者（あるいはプ口グラム）への制約事項／前提条件の記述漏れがないか。
		当該文書全体を通して表現の一体感／統ー感があるか。
		誤記がないか。
	記載具備の充足性	表紙があるか。
		文書管理番号・文書名を記載しているか。
		改訂履歴に、版、発行日、区分（機能変更・不具合修正等）、箇所、目的（要旨）を記載しているか。
		汎用の表記法を採用する場合、冒頭で表記法の表明（例：UML2.0準拠）があるか。
		独自の表記法を採用する場合、冒頭で表記法の説明があるか。
		図・表がある場合、「図（表）番号」の記述漏れがないか。
		図がある場合、「図の見方」または「凡例」の記述漏れかないか。

上記確認項目は、次世代の設計者が設計書を改版する際にも、設計書の品質水準を維持するための開発部隊のＤＮＡにする。
その連鎖は、さらに次世代のプログラム改善を担当する技術者の拠り所となる。

ステップアップを目指す方は「ソフトウエア設計シリーズ『離』」へお進みください。
ソフトウエア設計シリーズの目次はこちらへ

ソフトウエア設計書に書きたい項目－ソフトウエア設計シリーズ「破」⑦

ソフトウエア開発の設計レビュ―観点

設計レビューの確認項目例

コメント