みなさま、こんにちは。
コンタクトセンターソリューショングループの Kojima.h です。
普段は業務系システムの設計や開発に携わっており、設計、製造、テスト、保守と一連の工程を見る機会が多い立場にいます。
その中で感じるのは後工程で発生する確認や調整の多くは、実装ミスそのものよりも設計書の段階で前提が十分に記載されていなかったことに起因しているケースが少なくないという点です。
今回は、設計書を書く際にあらかじめどのような内容を明文化しておくと後工程での確認や調整が比較的楽になるか、という観点で整理してみました。
目次
明文化が必要だと感じた背景
設計書は開発工程が進むにつれて参照される場面が増えていきます。
製造、テスト、運用、保守といった後工程で設計書を確認した際に記載が足りず対応に苦労する場面を見かけることがあります。
こうした記載不足による認識のずれが生じることもあれば、不具合発生のきっかけになることもあり、結果として手戻りや工数増加につながるケースが発生します。
今回取り上げる「明文化」は、設計の正しさを保証するためというよりも後工程で確認が発生しやすいポイントをあらかじめ設計書に記載しておくこと、という観点で重要だと考えています。
以降の章では、記載不足として影響が出やすい「変数」「ログ」「異常系」という観点について、どのような内容を明文化しておくと楽になるかを整理していきます。
変数に関する明文化
変数は設計書の中でも比較的早い段階で定義されるため、型や桁数といった基本的な情報は記載されていることが多い項目です。
一方で、値の取り得る範囲や未設定時の扱いまで踏み込んで記載されていない場合に後工程で確認が発生しやすくなります。
設計書では、以下のような形で変数が定義されていることが多いと思います。
| 項目名 | 型 | 桁数 |
|---|---|---|
| 顧客ID | STRING | 10 |
| 顧客名 | STRING | 50 |
| 契約日 | DATE | 8 |
| 完了日 | DATE | 8 |
| 契約金額 | STRING | 10 |
もちろんこれらの情報は重要ですが、形式だけでは判断に迷う場面もあります。
例えば、以下のような点は表だけからは読み取れません。
- 顧客IDに記号が含まれることがあるのか
- 完了日が未設定の場合に「NULL」なのか「00000000」なのか、
あるいは別の初期値が想定されているのか - 契約金額がSTRINGになっているが、
0埋めのためなのか、カンマなどの文字を含めるためなのか
そこで具体例や備考を設計書に明文化しておくことで、後工程での判断を減らすことができます。
| 項目名 | 型 | 桁数 | 具体例 | 備考 |
|---|---|---|---|---|
| 顧客ID | STRING | 10 | 0123-45678 | ハイフン区切り |
| 顧客名 | STRING | 50 | コキャクメイ | 全角カタカナ |
| 契約日 | DATE | 8 | 20260401 | 初期値は00000000 |
| 完了日 | DATE | 8 | 20260430 | 初期値は00000000 |
| 契約金額 | STRING | 10 | 0001000000 | 0埋め |
ログに関する明文化
ログについては、設計や製造の段階では特に問題にならなくても保守のタイミングで初めて困ることが多い項目です。
実際に保守の場面では、障害調査や仕様確認のためにログを確認してもらう際に「そもそもログがどこに出力されているのか分からない」といった状況が発生することがあります。
また、ログの扱いについて設計段階で前提が整理されていない場合、ログが蓄積し続け、結果としてディスク容量の逼迫を引き起こすケースもあります。
こうした問題を振り返ると、次のような点が設計書で明文化されていなかったことが原因になっていると考えられます。
- ログがどこに出力される想定なのか
- ログをどのように管理する前提なのか
ログについては「何を出力するか」だけでなく、出力場所や管理の前提まで含めて設計書に明文化しておくことで、保守時の調査や運用上のトラブルを減らすことにつながると考えています。
異常系に関する明文化
異常系については重要であることは認識されている一方で、設計書では前提や方針が十分に整理されないまま進んでしまうことがある項目です。
異常が発生した場合の処理について、個々のチェックやエラーハンドリングは設計されていても処理全体としてどのように振る舞うのか、設計書から読み取りづらいケースがあります。
例えば、顧客リストのようなデータを一括で処理するケースでX件のうち途中の1件だけ処理に失敗した場合に
- 後続の処理を継続するのか
- その時点で処理を中断するのか
といった点は、設計書に記載がなければ判断が分かれやすい部分です。
この前提が整理されていないと、実装やテストの段階で「この場合はどこまで処理される想定なのか」といった確認が必要になります。
また、こうした異常時の振る舞いは、運用や保守の場面においても影響します。
処理がどこまで進んでいる想定なのかが分からないと、影響範囲の確認や再実行の判断に時間がかかる原因になります。
異常系は設計書上で個別のケースまで含めて整理されていることが多い一方で、異常発生時に処理全体がどのように進むのか、どこで止まる想定なのかといった立ち振る舞いの前提は記載が漏れやすい項目です。
そのため、この観点は設計段階で明文化しておく必要があると考えています。
おわりに
ここまで挙げた内容はいずれも必ずしも正解があるものではありません。
案件や現場によって妥当な落としどころは異なると思います。
ただ、設計書に書かれていないことは、後工程で誰かが判断することになるという前提で見てみると、あらかじめ明文化しておいた方が楽になるポイントは多くあります。
設計を書く際の一つの考え方として、どこかの現場で参考になれば幸いです。
