その設計書、仕様書ではなくポエムになっていませんか

システム開発の現場では、読んだ瞬間は分かった気になるのに、実装しようとすると何も決められない設計書があります。

例えば、次のような記述です。

ユーザー情報の取得。
入力内容の確認。
必要に応じたエラー処理。
適切なログ出力。
問題がなければ登録。

意味は何となく伝わります。

しかし、実装者によって解釈が変わります。

どこからユーザー情報を取得するのか
何を確認するのか
どの条件でエラーになるのか
どのログレベルで何を出力するのか
何をもって「問題がない」と判断するのか

このように、雰囲気は伝わるものの、実装に必要な情報が書かれていない設計書を、ここでは「ポエム化した設計書」と呼びます。

ポエム化した設計書とは

ポエム化した設計書には、次の特徴があります。

抽象的な言葉が多い
主語がない
条件が書かれていない
処理結果が不明
数値や具体的な判定基準がない
読む人が行間を補う必要がある

文章としては成立していても、仕様としては成立していません。

設計書の役割は、設計者の意図を何となく伝えることではありません。

実装者、レビュー担当者、テスト担当者が、同じ動作を理解できる状態を作ることです。

よくあるポエム表現

適切に処理する

エラーが発生した場合は適切に処理する。

何をすれば「適切」なのかが分かりません。

エラーメッセージを表示するのか
ログを出力するのか
リトライするのか
処理を中断するのか
管理者へ通知するのか

改善例は次のとおりです。

データベース接続で例外が発生した場合、APIサーバーはエラーログを出力し、HTTPステータスコード500を返して処理を中断する。

必要に応じて実行する

必要に応じて通知メールを送信する。

必要かどうかを誰が、何を基準に判断するのかが不明です。

改善例です。

注文金額が10万円以上の場合、システムは承認担当者へ通知メールを送信する。

一定時間待機する

外部APIの応答がない場合は一定時間待機する。

「一定時間」が1秒なのか30秒なのか分かりません。

改善例です。

外部APIから10秒以内に応答がない場合、システムはタイムアウトとして処理を中断する。

問題がなければ登録する

入力内容に問題がなければデータを登録する。

何を問題と判断するのかが書かれていません。

改善例です。

必須項目がすべて入力され、メールアドレス形式が正しく、同一メールアドレスが登録されていない場合、APIサーバーはユーザー情報を登録する。

エラー時はメッセージを表示する

エラー時は適切なメッセージを表示する。

どのエラーで、どのメッセージを、どこに表示するのかが不明です。

改善例です。

メールアドレスが未入力の場合、画面はメールアドレス入力欄の下に「メールアドレスを入力してください」と表示する。

ポエム化する原因

設計者の頭の中では分かっている

設計者は、業務やシステムの前提を理解しています。

そのため、自分にとって当然のことを省略してしまいます。

しかし、読む側は同じ前提を持っているとは限りません。

「これくらい分かるだろう」という省略が、設計書のポエム化につながります。

文章を短くしようとしすぎる

設計書は簡潔であるべきですが、情報まで削ってはいけません。

例えば、次の文章は短いですが、仕様として不足しています。

権限チェックを行う。

次のように書けば、処理内容が明確になります。

APIサーバーは、ログインユーザーが管理者権限を持つことを確認する。管理者権限を持たない場合、HTTPステータスコード403を返す。

設計書では、文字数を減らすことよりも、解釈の幅を減らすことが重要です。

抽象語で逃げてしまう

次の言葉は便利ですが、設計書では注意が必要です。

適切に
必要に応じて
原則として
基本的に
通常は
速やかに
十分な
大量の
一定時間
問題がある場合

これらの言葉を使ったときは、具体的な条件や数値に置き換えられないか確認する必要があります。

ポエム化した設計書が引き起こす問題

実装者ごとに動作が変わる

設計書に具体的な条件が書かれていないと、実装者が自分で判断します。

その結果、担当者ごとに異なる実装が生まれます。

例えば、

エラー時はログを出力する。

という記述だけでは、次のような違いが発生します。

エラーレベルで出力する人
警告レベルで出力する人
例外メッセージだけ出力する人
スタックトレースまで出力する人
個人情報まで出力してしまう人

設計書が曖昧なほど、実装品質は担当者の経験に依存します。

レビューで正誤を判断できない

設計書に期待動作が書かれていなければ、実装が正しいか判断できません。

レビュー担当者も、自分の解釈で確認することになります。

結果として、レビューが仕様確認ではなく、好みの確認になります。

テストケースを作れない

次の記述からは、具体的なテストケースを作れません。

入力値に問題がある場合、エラーとする。

一方、次の記述ならテストできます。

顧客名が未入力の場合、画面は「顧客名を入力してください」と表示し、登録APIを呼び出さない。

設計書を読んでテストケースを作れない場合、その設計書はポエム化している可能性があります。

障害時に責任範囲が曖昧になる

曖昧な設計書では、障害が起きたときに次の議論が発生します。

設計どおりに実装した
そこまで書いていなかった
普通はこう解釈する
その動作を想定していた
実装者なら分かるはずだった

これは個人の能力だけの問題ではありません。

設計書に判断基準が書かれていないことが原因です。

ポエム化を防ぐ書き方

設計書では、少なくとも次の4点を書きます。

誰が
どの条件で
何を行い
どのような結果になるのか

基本形は次のとおりです。

○○は、△△の場合、□□を実行し、××とする。

例えば、次のように書きます。

APIサーバーは、指定されたユーザーIDに一致するユーザーが存在する場合、そのユーザー情報を返す。

指定されたユーザーIDに一致するユーザーが存在しない場合、APIサーバーはHTTPステータスコード404を返す。

外部APIから10秒以内に応答がない場合、APIサーバーは処理を中断し、タイムアウトエラーを返す。

これだけでも、設計書の解釈の幅は大きく減ります。

悪い例と改善例

悪い例

ユーザー情報の取得。

改善例

APIサーバーは、リクエストで指定されたユーザーIDを検索条件として、ユーザーテーブルからユーザー情報を1件取得する。

悪い例

入力内容のチェック。

改善例

APIサーバーは、ユーザー名が未入力の場合、エラーコード USER_NAME_REQUIRED を返し、登録処理を実行しない。

悪い例

必要に応じて再実行する。

改善例

外部APIがHTTPステータスコード503を返した場合、システムは5秒間隔で最大3回まで再実行する。

悪い例

エラー内容をログへ出力する。

改善例

予期しない例外が発生した場合、APIサーバーはエラーレベルで例外メッセージ、スタックトレース、リクエストIDをログへ出力する。

悪い例

検索結果を一覧表示する。

改善例

画面は、検索条件に一致した顧客情報を更新日時の降順で表示する。検索結果が0件の場合は「該当する顧客が見つかりませんでした」と表示する。

ポエム化を見抜くチェック方法

設計書をレビューするときは、次の質問をします。

この文章だけで実装方法を決められるか
正常系と異常系を区別できるか
条件をテストケースに変換できるか
数値や判定基準が書かれているか
読む人によって解釈が変わらないか
「適切に」や「必要に応じて」を具体化できないか

特に有効なのは、次の確認です。

この設計書だけを渡して、別のエンジニアが同じ実装を作れるか。

同じ実装にならないのであれば、設計書の情報が不足しています。

設計書は余白を読ませない

良い文学作品では、読み手に解釈を委ねる余白が魅力になります。

しかし、設計書では余白が障害の原因になります。

設計書に必要なのは、表現の美しさではありません。

条件
数値
処理主体
入出力
正常時の動作
異常時の動作

これらを明確に書くことが重要です。

設計書は、読者に想像させる文章ではありません。

読者の想像を減らす文章です。

まとめ

ポエム化した設計書は、意味が分からない設計書ではありません。

読めば何となく意味は分かるものの、実装、レビュー、テストに必要な情報が不足している設計書です。

次のような表現が多い場合は注意が必要です。

適切に処理する
必要に応じて実行する
問題がなければ登録する
一定時間待機する
エラー時はメッセージを表示する

設計書を書くときは、次の形を意識します。

誰が、どの条件で、何を行い、どのような結果にするのか。

設計書の目的は、設計者の意図を雰囲気で伝えることではありません。

誰が読んでも、同じ動作を実装し、同じ基準で確認できる状態を作ることです。

設計書をポエムにしないために、行間ではなく仕様を書きましょう。