前編では、外部設計書を書くときの考え方を整理しました。
外部設計書は、自分が理解するためのメモではありません。
お客様、レビュー者、実装者、テスト担当者、保守担当者、そして未来の自分が読んでも、同じ判断ができる必要があります。
後編では、ECサイトの注文管理画面を例にして、レビューで止まりやすい書き方を見ていきます。
この記事に出てくる画面名、項目名、処理内容はすべて架空の例です。
外部設計書で起きやすい指摘を説明するために、ECサイト向けの例として再構成しています。
この記事で扱うこと
この記事では、外部設計書でレビュー指摘になりやすい書き方を、次の形で整理します。
悪い例
↓
何が悪いか
↓
修正例
扱う観点は次のとおりです。
- 画面とダイアログの混同
- メニュー追加とダイアログ表示の混在
- 「等」「任意」の曖昧さ
- 活性、不活性、非表示の条件不足
- エラー時の状態不足
- 計算仕様の不足
- 見出しと中身の不一致
- 読みやすい空間の作り方
- 画像注釈と本文の対応不足
- 表記ゆれ
- 何が、何を、どうするのか分からない説明
- 「かつ」「または」が曖昧な条件
- 条件の片側だけを書いている仕様
- 対象を選ぶ条件が不足している仕様
- 「行います」「調整します」だけで終わる説明
最初に結論
外部設計書では、文章として意味が通るだけでは足りません。
読み手が、次のことを判断できる必要があります。
| 観点 | 判断したいこと |
|---|---|
| 対象 | どの画面、項目、ボタン、データの話か |
| 条件 | どの状態で処理するのか |
| 処理 | 何をするのか |
| 結果 | 処理後に何が変わるのか |
| 例外 | 処理できない場合にどうなるのか |
| 表示 | 画面、メッセージ、ボタン状態がどうなるのか |
| テスト | 何を確認すればよいのか |
この情報が不足すると、読み手は仕様を読むのではなく、仕様を推測することになります。
例1. 画面とダイアログを混同している
悪い例
クーポン入力画面を追加します。
何が悪いか
「画面」と書くと、新しい画面を作成するように読めます。
しかし、実際には注文確認画面からダイアログを表示するだけかもしれません。
画面を追加するのか。
既存画面にボタンを追加するのか。
ボタン押下時にダイアログを表示するのか。
ここが曖昧だと、実装範囲が変わります。
テスト担当者も、新画面の遷移を確認するのか、既存画面上のダイアログ表示を確認するのか判断できません。
修正例
注文確認画面に「クーポン適用」ボタンを追加します。
「クーポン適用」ボタン押下時は、クーポン適用ダイアログを表示します。
画面、ボタン、ダイアログを分けて書くと、実装範囲が明確になります。
例2. メニュー追加と表示処理が混ざっている
悪い例
注文管理画面の操作メニューに「クーポン適用ダイアログ」を追加します。
何が悪いか
メニューに追加するのは、通常はメニュー項目です。
ダイアログそのものをメニューに追加するわけではありません。
この書き方だと、次の2つが混ざっています。
| 内容 | 本来分けるべきこと |
|---|---|
| メニューに何を追加するか | 「クーポン適用」メニュー |
| メニュー選択時に何を表示するか | クーポン適用ダイアログ |
外部設計書では、操作の入口と、操作後の結果を分けて書いた方が読みやすくなります。
修正例
注文管理画面の操作メニューに「クーポン適用」を追加します。
「クーポン適用」選択時は、クーポン適用ダイアログを表示します。
メニュー名とダイアログ名を分けることで、画面仕様と操作仕様が明確になります。
例3. 「等」で対象をぼかしている
悪い例
法人会員等の場合は、クーポンを使用できません。
何が悪いか
「等」に何が含まれるのか分かりません。
法人会員だけなのか。
ゲスト購入も含むのか。
退会済み会員も含むのか。
ブラックリスト会員も含むのか。
読み手が判断することになります。
外部設計書で「等」を使うと、対象範囲が曖昧になります。
対象範囲が曖昧だと、実装条件もテストケースも曖昧になります。
修正例
以下の購入者区分では、クーポンを使用できません。
- 法人会員
- ゲスト購入
- 退会済み会員
通常会員の場合は、クーポンを使用可能とします。
対象外だけでなく、対象になる側も書くと判断しやすくなります。
「等」は便利ですが、仕様書では読み手に判断を渡しやすい表現です。
対象が決まっている場合は、すべて明記した方が安全です。
例4. 「任意」の範囲が分からない
悪い例
クーポン割引額には任意の金額を入力できます。
何が悪いか
「任意の金額」だけでは、入力可能な範囲が分かりません。
- 0円は可能なのか
- マイナス値は可能なのか
- 小数は可能なのか
- 上限はあるのか
- 商品合計金額を超えてよいのか
読み手によって解釈が分かれます。
実装者は入力制限を決められません。
テスト担当者も、どの境界値を確認すべきか判断できません。
修正例
クーポン割引額には、0円以上、商品小計（税込）以下の整数を入力可能とします。
小数、マイナス値、商品小計（税込）を超える金額は入力不可とします。
入力可能な範囲と、入力不可の範囲を明記すると、境界値テストに落としやすくなります。
例5. 活性、不活性、非表示の条件が曖昧
悪い例
キャンセルできない注文では、キャンセルボタンを使用できないようにします。
何が悪いか
「使用できないようにします」だけでは、画面上の状態が分かりません。
- ボタンを非表示にするのか
- ボタンを不活性にするのか
- 押下時にエラーを表示するのか
- メニュー項目を表示しないのか
この違いは、画面仕様として重要です。
お客様が見る画面も変わります。
テストケースも変わります。
修正例
注文ステータスが「出荷済み」の場合、キャンセルボタンを不活性とします。
注文ステータスが「キャンセル済み」の場合、キャンセルボタンを非表示とします。
注文ステータスが「注文受付」の場合、キャンセルボタンを活性とします。
条件ごとに、活性、不活性、非表示を明記します。
可能であれば、活性条件と不活性条件を同じ粒度で書きます。
例6. 条件と結果がセットになっていない
悪い例
在庫がない場合は注文できません。
何が悪いか
意味は分かります。
しかし、外部設計書としては情報が足りません。
- どのタイミングで在庫を確認するのか
- 注文確定ボタンを押す前に判定するのか
- 注文確定ボタン押下時に判定するのか
- メッセージを表示するのか
- 注文データは作成されるのか
- カート内容は残るのか
「注文できません」だけでは、処理結果が分かりません。
修正例
注文確定ボタン押下時、注文商品の在庫数を確認します。
在庫数が注文数量を下回る商品が存在する場合は、在庫不足メッセージを表示し、注文確定処理を実行しません。
メッセージを閉じた後は、注文確認画面に戻ります。
カート内容、配送先、支払方法は注文確定前の状態から変更しません。
条件、処理、結果、保持する状態を分けて書くと、実装とテストに落としやすくなります。
例7. エラー時に何が変わらないかを書いていない
悪い例
クーポンが無効な場合は、エラーメッセージを表示して処理を中止します。
何が悪いか
エラーメッセージを表示することは分かります。
しかし、処理中止後の状態が分かりません。
- 入力したクーポンコードは残るのか
- 割引額は変更されるのか
- 合計金額は元のままか
- ダイアログは閉じるのか
- 注文確認画面に戻るのか
外部設計書では、エラー時に「何を変更しないか」も重要です。
修正例
クーポンコードが無効な場合は、クーポン無効メッセージを表示し、クーポン適用処理を中止します。
メッセージを閉じた後も、クーポン適用ダイアログは表示したままとします。
入力されたクーポンコードは保持します。
割引額、送料、請求合計金額は、クーポン適用前の状態から変更しません。
エラー時の状態を明記すると、実装者もテスト担当者も判断しやすくなります。
エラー時は「何をするか」だけでなく、「何を変えないか」も書くと仕様が安定します。
例8. 「既存仕様と同様」が何を指すか分からない
悪い例
ポイント付与は既存仕様と同様に処理します。
何が悪いか
書いた本人は、どの既存仕様を指しているか分かっているかもしれません。
しかし、読み手には分かりません。
- 通常注文のポイント付与と同じなのか
- 予約注文のポイント付与と同じなのか
- キャンペーン商品のポイント付与と同じなのか
- どの設計書、どの章を見ればよいのか
「既存仕様と同様」は、参照先が明確でないと読み手に調査をさせる表現になります。
修正例
ポイント付与数は、通常注文時のポイント付与仕様と同じ計算式で算出します。
ポイント付与数 ＝ 商品小計（税込） × 会員ランク別ポイント付与率
算出結果に小数が発生した場合は、小数点以下を切り捨てます。
参照先がある場合は、章番号や資料名を示します。
ポイント付与の基本仕様は、「4.2.1 通常注文時のポイント付与仕様」に従います。
参照先を示せない場合は、その場に動きを書いた方が安全です。
例9. 計算仕様の式、丸め、表示桁が不足している
悪い例
商品金額に応じて送料を計算します。
何が悪いか
計算条件が分かりません。
- 商品金額とは税込か、税抜か
- クーポン適用前か、適用後か
- 送料判定に手数料を含めるのか
- 5,000円ちょうどは無料になるのか
- 小数が発生するのか
- 表示桁はどうするのか
計算仕様は、曖昧さがあると実装結果がずれやすいです。
テストケースも境界値を作れません。
修正例
送料判定金額は、以下の計算式で算出します。
送料判定金額 ＝ 商品小計（税込） － クーポン割引額
送料判定金額が5,000円以上の場合、送料を0円とします。
送料判定金額が5,000円未満の場合、送料を500円とします。
送料判定金額に小数は発生しません。
小数が発生する場合は、丸めも書きます。
ポイント付与数は、以下の計算式で算出します。
ポイント付与数 ＝ 商品小計（税込） × ポイント付与率
算出結果に小数が発生した場合は、小数点以下を切り捨てます。
ポイント付与数は整数で表示します。
計算仕様は、式、条件、丸め、表示桁をセットで書くと読みやすくなります。
例10. 「加算」「減算」「反映」の使い分けが曖昧
悪い例
割引額を請求金額に加算します。
何が悪いか
割引額は、通常は請求金額から差し引くものです。
「加算」と書くと、請求金額が増えるように読めます。
もし割引額がマイナス値として保持されている場合でも、読み手には分かりません。
金額系の仕様では、加算、減算、反映の使い分けが重要です。
修正例
請求合計金額からクーポン割引額を減算します。
または、符号によって増減が変わる場合は、無理に加算や減算と書かず、反映と書く方が自然です。
調整額を請求合計金額に反映します。
調整額が正の値の場合、請求合計金額は増加します。
調整額が負の値の場合、請求合計金額は減少します。
金額が増えるのか、減るのか、条件によって変わるのかを明記します。
例11. 見出しと中身が合っていない
悪い例
## クーポン適用機能・画面イメージ
- クーポンコード入力欄を表示します。
- 適用ボタン押下時は、クーポンを検証します。
- クーポンが無効な場合は、エラーメッセージを表示します。
- 画面イメージを以下に示します。
何が悪いか
見出しの中に、複数の役割が混ざっています。
- 画面項目
- 操作仕様
- エラー仕様
- 画面イメージ
これらは、読み手が探したい場面が違います。
実装者は画面項目を探します。
テスト担当者は操作結果やエラー条件を探します。
お客様は画面イメージと動きを確認します。
1つの見出しに混ざっていると、必要な仕様を探しにくくなります。
修正例
## クーポン適用ダイアログ
### 画面仕様
- クーポンコード入力欄を表示します。
- 適用ボタンを表示します。
- キャンセルボタンを表示します。
### 操作仕様
- 適用ボタン押下時は、入力されたクーポンコードを検証します。
- キャンセルボタン押下時は、クーポンを適用せずにダイアログを閉じます。
### エラー仕様
- クーポンコードが未入力の場合、未入力メッセージを表示します。
- クーポンコードが無効な場合、クーポン無効メッセージを表示します。
### 画面イメージ
- クーポン適用ダイアログの画面イメージを示します。
見出しを分けると、仕様の置き場所が明確になります。
例12. 読みやすい空間がなく、仕様を探しにくい
悪い例
注文確定ボタン押下時は入力内容を確認し、在庫が不足している場合はエラーメッセージを表示して処理を中止します。クーポンコードが入力されている場合はクーポンを検証し、使用できない場合はエラーメッセージを表示します。使用可能な場合は割引額を計算し、送料を計算し、請求合計金額を表示します。注文ステータスが出荷済みの場合はキャンセルできません。
何が悪いか
文章としては読めます。
しかし、仕様としては探しにくいです。
- 入力チェック
- 在庫確認
- クーポン検証
- 金額計算
- キャンセル可否
これらが1つの段落に詰め込まれています。
読み手は、どこに何が書かれているかを探す必要があります。
外部設計書では、内容を詰め込むほど親切になるわけではありません。
仕様を探すための空間が必要です。
ここでいう空間は、見た目の余白だけではありません。
見出し、表、箇条書き、段落分けによって、情報の置き場所を作ることです。
修正例
### 注文確定ボタン押下時
注文確定ボタン押下時は、以下の順序で処理します。
1. 入力内容を検証します。
2. 在庫数を確認します。
3. クーポンコードを検証します。
4. 請求合計金額を算出します。
5. 注文データを登録します。
### 在庫不足時
在庫数が注文数量を下回る商品が存在する場合は、在庫不足メッセージを表示し、注文確定処理を実行しません。
メッセージを閉じた後は、注文確認画面に戻ります。
カート内容、配送先、支払方法は注文確定前の状態から変更しません。
### クーポン使用不可時
クーポンコードが無効な場合は、クーポン無効メッセージを表示し、クーポン適用処理を中止します。
割引額、送料、請求合計金額は、クーポン適用前の状態から変更しません。
### キャンセルボタンの状態
| 注文ステータス | キャンセルボタン |
|---|---|
| 注文受付 | 活性 |
| 出荷済み | 不活性 |
| キャンセル済み | 非表示 |
仕様の種類ごとに区切ると、読み手が必要な情報にたどり着きやすくなります。
外部設計書では、文章量を減らすことだけが読みやすさではありません。
見出し、表、箇条書きで情報の置き場所を作ると、レビュー、実装、テストで探しやすくなります。
例13. 画像の吹き出しと本文が対応していない
悪い例
以下の画面イメージに、クーポン適用前後の金額を示します。
対象金額：5,500円
割引額：500円
請求合計金額：5,000円
何が悪いか
本文に項目名はあります。
しかし、画面イメージ上のどの部分を指しているのか分からない場合があります。
特に、画面上に似た金額が複数ある場合は危険です。
- 商品小計
- 送料
- 割引額
- 請求合計金額
- ポイント利用額
本文と画像が対応していないと、読み手は推測することになります。
修正例
画面イメージの各項目を以下に示します。
A) 商品小計：5,500円
B) クーポン割引額：500円
C) 請求合計金額：5,000円
C) 請求合計金額は、以下の計算式で算出します。
C) 請求合計金額 ＝ A) 商品小計 － B) クーポン割引額
画面イメージ側にも、A)、B)、C) の吹き出しを付けます。
本文と画像の番号を合わせると、読み手が追いやすくなります。
例14. 画面上の行番号だけで説明している
悪い例
No.3の金額を更新します。
何が悪いか
画面イメージの行番号だけを本文で参照すると、読み手が対象を特定しにくくなります。
画面キャプチャが差し替わると、行番号が変わる可能性もあります。
また、No.3が何を意味する行なのかが本文だけでは分かりません。
外部設計書では、行番号だけでなく、判定条件や対象の意味も書いた方が安全です。
修正例
割引対象商品のうち、商品金額が最大となる行の割引額に調整差額を反映します。
本例では、No.3行（商品名：ワイヤレスイヤホン、商品金額：12,000円）の割引額に反映します。
条件を先に書き、例として行番号を補足すると、画像が変わっても仕様の意味が残ります。
例15. 表記ゆれで同じものか別のものか分からない
悪い例
顧客IDを入力します。
会員IDに紐づく注文履歴を表示します。
ユーザーIDが一致しない場合はエラーとします。
何が悪いか
顧客ID、会員ID、ユーザーIDが同じものなのか、別のものなのか分かりません。
同じものなら表記ゆれです。
別のものなら、違いを定義する必要があります。
表記ゆれがあると、読み手は毎回確認することになります。
修正例
同じものを指す場合は、表記を統一します。
会員IDを入力します。
会員IDに紐づく注文履歴を表示します。
会員IDが一致しない場合はエラーとします。
別のものを指す場合は、違いを定義します。
会員IDは、ログイン会員を識別するIDです。
顧客IDは、基幹システム上の顧客を識別するIDです。
注文履歴検索では、会員IDに紐づく顧客IDを取得し、顧客IDに一致する注文履歴を表示します。
同じものは同じ名前で書きます。
違うものは、違いが分かるように書きます。
表記ゆれは、単なる文章の問題ではありません。
外部設計書では、同じ仕様なのか、別の仕様なのかを判断できなくする原因になります。
例16. 「今回の例」という表現を使っている
悪い例
今回の例では、クーポン割引額を500円とします。
何が悪いか
「今回」が何を指すのか分かりにくいです。
この設計書を後から読む人にとっては、いつの今回なのか判断できません。
機能追加や改修で同じ章が更新された場合、さらに分かりにくくなります。
仕様書では、時間や会話に依存する表現は避けた方がよいです。
修正例
本例では、クーポン割引額を500円とします。
または、例の目的を明記します。
以下の例では、クーポン適用後の請求合計金額の算出方法を示します。
「今回」ではなく、「本例」「以下の例」と書くと、文書内の説明として自然になります。
例17. 何が、何を、どうするのか分からない
悪い例
注文確定時に、対象データを更新します。
何が悪いか
文章としては読めます。
しかし、仕様としてはほとんど情報がありません。
- 何が処理を行うのか
- どのデータを対象にするのか
- どの項目を更新するのか
- 何から何へ更新するのか
- 更新後に画面表示は変わるのか
- 更新できない場合はどうするのか
「対象データを更新します」だけでは、実装者は何を作ればよいか判断できません。
テスト担当者も、何を確認すればよいか分かりません。
外部設計書では、処理名だけで終わらせず、対象、項目、変更内容、結果まで書く必要があります。
修正例
注文確定ボタン押下時は、注文データの注文ステータスを「注文受付」から「注文確定」に更新します。
更新後は、注文確認画面を閉じ、注文完了画面を表示します。
注文完了画面には、注文番号、請求合計金額、配送予定日を表示します。
このように書くと、何が、何を、どうするのかが分かります。
| 観点 | 内容 |
|---|---|
| いつ | 注文確定ボタン押下時 |
| 何を | 注文データの注文ステータス |
| どうする | 「注文受付」から「注文確定」に更新する |
| 結果 | 注文完了画面を表示する |
| 表示内容 | 注文番号、請求合計金額、配送予定日を表示する |
仕様書では、読み手が処理を想像しなくてよい状態まで書くことが大切です。
例18. 「かつ」「または」が曖昧
悪い例
クーポンコードが未入力、有効期限切れの場合はエラーとします。
何が悪いか
この書き方では、条件の関係が曖昧です。
- 未入力の場合にエラーなのか
- 有効期限切れの場合にエラーなのか
- 両方を満たした場合だけエラーなのか
- どちらか一方を満たせばエラーなのか
読み手が条件を補完する必要があります。
条件の解釈がずれると、実装もテストケースも変わります。
外部設計書では、条件が複数ある場合、「かつ」なのか「または」なのかを明記します。
修正例
どちらか一方を満たせばエラーにする場合は、次のように書きます。
以下のいずれかに該当する場合は、クーポンエラーメッセージを表示します。
- クーポンコードが未入力である
- クーポンコードの有効期限が切れている
すべてを満たす場合だけエラーにするなら、次のように書きます。
以下の条件をすべて満たす場合は、クーポン利用不可メッセージを表示します。
- クーポンコードが入力されている
- クーポンコードの有効期限が切れている
- 注文ステータスが「注文受付」である
「いずれか」なのか「すべて」なのかを書くと、実装者とテスト担当者の解釈が揃いやすくなります。
例19. 条件の片側しか書かれていない
悪い例
配送先が登録されている場合は、配送先情報を表示します。
何が悪いか
登録されている場合の動きは分かります。
しかし、登録されていない場合の動きが分かりません。
- 空欄で表示するのか
- 未登録メッセージを表示するのか
- 配送先登録画面へ誘導するのか
- 注文確定ボタンを不活性にするのか
- 注文手続き自体を進められないのか
片側の条件だけを書くと、反対側の動きを読み手が補完することになります。
仕様書では、条件が分かれる場合、両方の結果を書いた方が安全です。
修正例
配送先が登録されている場合は、注文確認画面に配送先情報を表示します。
配送先が登録されていない場合は、配送先未登録メッセージを表示し、注文確定ボタンを不活性とします。
配送先未登録メッセージの「配送先を登録する」リンク押下時は、配送先登録画面を表示します。
条件の片側だけでなく、反対側の動きも書くと、画面仕様とテスト観点が明確になります。
例20. 対象を選ぶ条件が不足している
悪い例
割引対象行に調整額を反映します。
何が悪いか
どの行に反映するのかが分かりません。
割引対象行が1行だけなら問題にならないかもしれません。
しかし、複数行ある場合は、実装者が対象行を選ぶ必要があります。
- 商品金額が最大の行なのか
- 明細番号が最小の行なのか
- 数量が最大の行なのか
- 最初に表示されている行なのか
- 同じ条件の行が複数ある場合はどうするのか
対象を選ぶ条件が曖昧だと、実装結果が人によって変わります。
テスト担当者も、どの行を確認すればよいか判断できません。
修正例
割引対象商品のうち、商品金額が最大となる行に調整額を反映します。
商品金額が最大となる行が複数存在する場合は、明細番号が最小の行に調整額を反映します。
本例では、No.3行（商品名：ワイヤレスイヤホン、商品金額：12,000円）に調整額を反映します。
対象を選ぶ条件と、同値時の優先順位を書いておくと、実装者が判断を補完せずに済みます。
例21. 「行います」「調整します」だけで終わっている
悪い例
クーポン適用時は、金額の調整を行います。
何が悪いか
「金額の調整」だけでは、何をどう変えるのか分かりません。
- 商品小計を変えるのか
- 割引額を変えるのか
- 送料を変えるのか
- 請求合計金額を変えるのか
- ポイント付与数も変えるのか
「行います」「調整します」は便利ですが、処理内容を隠してしまうことがあります。
修正例
クーポン適用時は、クーポン割引額を算出し、請求合計金額に反映します。
請求合計金額は、以下の計算式で算出します。
請求合計金額 ＝ 商品小計（税込） ＋ 送料 － クーポン割引額
何をどう変えるのかを書きます。
仕様書では、処理名だけで終わらせず、対象項目と変更内容まで書くと伝わりやすくなります。
例22. 処理順序が分からない
悪い例
クーポン、送料、ポイントを計算し、請求合計金額を表示します。
何が悪いか
処理する内容は分かります。
しかし、順序が分かりません。
ECサイトでは、計算順序によって結果が変わることがあります。
- クーポン適用前の金額で送料を判定するのか
- クーポン適用後の金額で送料を判定するのか
- ポイント利用前の金額でポイント付与するのか
- ポイント利用後の金額でポイント付与するのか
順序が曖昧だと、実装結果やテスト結果がずれます。
修正例
請求合計金額は、以下の順序で算出します。
1. 商品小計（税込）を算出します。
2. クーポン割引額を算出します。
3. 送料判定金額を算出します。
4. 送料を算出します。
5. ポイント利用額を減算します。
6. 請求合計金額を算出します。
請求合計金額 ＝ 商品小計（税込） － クーポン割引額 ＋ 送料 － ポイント利用額
計算が複数ある場合は、順序を明記します。
例23. 中止後の画面状態が分からない
悪い例
入力エラーの場合は、登録処理を中止します。
何が悪いか
登録処理を中止することは分かります。
しかし、中止後の画面状態が分かりません。
- 入力画面に残るのか
- 一覧画面に戻るのか
- 入力値は保持されるのか
- エラー項目にフォーカスを当てるのか
- エラーメッセージはどこに表示されるのか
この情報がないと、実装者もテスト担当者も判断できません。
修正例
入力エラーがある場合は、登録処理を実行しません。
入力画面を表示したままとし、入力値は保持します。
エラー対象項目の下部にエラーメッセージを表示します。
初回のエラー対象項目にフォーカスを設定します。
中止後の画面状態を書くと、テストケースに落としやすくなります。
例24. 活性条件と不活性条件の粒度が揃っていない
悪い例
以下の場合、更新ボタンを不活性とします。
- 注文が確定済みの場合
- 入力エラーがある場合
入力可能な場合は、更新ボタンを使用できます。
何が悪いか
不活性条件は具体的ですが、活性条件が曖昧です。
「入力可能な場合」が何を指すのか分かりません。
確定済みでないこと。
入力エラーがないこと。
権限があること。
対象データが存在すること。
どこまで含むのかが分かりません。
修正例
以下の条件をすべて満たす場合、更新ボタンを活性とします。
- 注文ステータスが「下書き」である
- 入力エラーが存在しない
- ログインユーザーが注文更新権限を持つ
上記のいずれかを満たさない場合、更新ボタンを不活性とします。
活性条件と不活性条件は、同じ観点で書くと分かりやすくなります。
例25. 未来の自分が読んでも判断理由を追えない
悪い例
一部の注文では、クーポンを使用不可とします。
何が悪いか
今の自分は、打ち合わせの経緯を覚えているかもしれません。
しかし、1週間後、1か月後、1年後に読むと、なぜその条件にしたのか分からなくなる可能性があります。
外部設計書は、今の記憶で読む資料ではありません。
後から読んでも、判断理由を追える必要があります。
修正例
以下の注文では、クーポンを使用不可とします。
- 定期購入注文
- 予約商品を含む注文
- 法人会員の注文
定期購入注文および予約商品を含む注文では、販売価格が注文時点で確定しない場合があるため、クーポン割引の対象外とします。
法人会員の注文では、契約単価を適用するため、クーポン割引の対象外とします。
すべての仕様に理由を書く必要はありません。
ただし、読み手が「なぜ？」と思いやすい条件には、判断理由を添えると後から追いやすくなります。
未来の自分も読み手です。
今は覚えている判断理由でも、時間が経つと忘れます。
後から読んで迷いそうな条件には、理由を残しておくと保守しやすくなります。
レビュー前チェックリスト
外部設計書をレビューに出す前に、次の観点で確認すると指摘を減らしやすくなります。
対象が分かるか
- どの画面の話か
- どのダイアログの話か
- どのメニューの話か
- どのボタンの話か
- どの項目の話か
- どのデータの話か
- 複数候補がある場合、どれを対象にするか分かるか
- 同値や同順位の場合の優先順位が分かるか
条件が分かるか
- どのステータスの場合か
- どの購入者区分の場合か
- どの入力値の場合か
- どの権限の場合か
- どの条件をすべて満たすのか
- どれか1つでも満たせばよいのか
- 条件の片側だけでなく、反対側の動きも書かれているか
- 「かつ」「または」が明確か
結果が分かるか
- 画面表示がどう変わるか
- ボタンが活性か、不活性か、非表示か
- メッセージを表示するか
- データを登録するか
- データを更新するか
- どの項目を、どの値に変更するか
- 何を変更しないか
エラー時の状態が分かるか
- 処理を実行するのか、しないのか
- メッセージを閉じた後、どの画面にいるのか
- 入力値は保持されるのか
- データは変更されるのか
- フォーカスを移動するのか
- 再実行できる状態なのか
表記が揃っているか
- 同じ画面名を同じ表記で書いているか
- 同じ項目名を同じ表記で書いているか
- 同じボタン名を同じ表記で書いているか
- 活性、不活性、非表示を使い分けているか
- 登録、保存、更新を混同していないか
空間があるか
- 1つの段落に複数の仕様を詰め込んでいないか
- 画面仕様、操作仕様、エラー仕様を分けているか
- 表にした方が分かりやすい条件を文章だけで書いていないか
- 箇条書きにした方が追いやすい処理順序を長文で書いていないか
- 読み手が仕様を探しやすい見出しになっているか
テストケースに落とせるか
- 正常系の確認項目が分かるか
- 異常系の確認項目が分かるか
- 境界値が分かるか
- 丸めや表示桁が分かるか
- 画面状態やデータ状態の期待結果が分かるか
- 条件の組み合わせをテストケースにできるか
まとめ
外部設計書のレビューで指摘されるのは、文章がきれいではないからとは限りません。
読み手が判断できないから指摘されます。
- 何を対象にしているのか
- どの条件で動くのか
- 何が、何を、どうするのか
- 処理後に何が変わるのか
- エラー時に何が変わらないのか
- どの表記が正しいのか
- テストケースにどう落とすのか
- どこを読めば目的の仕様にたどり着けるのか
ここが曖昧だと、実装者、テスト担当者、レビュー者、お客様の認識がずれます。
外部設計書では、読み手に推測させないことが重要です。
特に、次の表現は注意が必要です。
| 表現 | 見直す観点 |
|---|---|
| 等 | 対象をすべて明記できないか |
| 任意 | 範囲や上限下限を書けないか |
| 適切に | 判断基準を書けないか |
| 同様に | 何と同じかを書けないか |
| 行います | 何をどうするかを書けないか |
| 調整します | どの項目をどう変えるかを書けないか |
| 中止します | 中止後の画面やデータ状態を書けないか |
| 対象データ | どのデータ、どの項目かを書けないか |
| 一部 | 対象条件を明記できないか |
外部設計書は、今の自分が分かればよい資料ではありません。
他の人が読んでも分かること。
テストケースに落とせること。
お客様が要件と合っているか確認できること。
1週間後、1か月後、1年後の自分が読んでも、同じ判断ができること。
そこまで書けているかを、レビュー前に確認した方がよいです。
関連記事
前編はこちらです。