はじめに
コーディングをするにあたり設計書のフローの部分に悩まされる事が多々あったので書いてみることにします
頭を悩まされた設計書
- 記載されている情報が少なく修正対象等が不明瞭
- DBを使用する機能だが対象のテーブルが記載されていない
- 機能、データの依存関係がハッキリしていない
- 処理に関して明記されていない
- スパゲッティのようになっており解読できない
どのように書くか
結論から言えば「頭を悩まされた設計書」に書いてある事の逆の事をすれば良いです。
それだけだと不親切なのでしっかり書きます。
- 改修作業の場合は対象を明確に記載する
- DBを使用する場合はテーブル、カラム、条件を明確に記載する
- 依存する機能やデータが存在する場合は明確に記載する
- 処理に関して大まかでも良いので記載する
- 動作毎に一つ一つ記載する
- 上から下に読むだけでおおよそ理解できるように記載する
上記を考慮したうえで他の人が読んでわかるように記載すると良いです。
設計書は自身のみが使用するものではなく、他の人も使用するものと意識するのが重要です。
記述例
適当に簡易的なログイン機能を例に文章ベースで記載してみます。
1.IDの取得を行う
1-1.IDの入力値のチェックを行う
1-1-1.入力値が存在しなかった場合、入力値が存在しない旨のエラーメッセージを返却する
1-1-2.入力値が不正な入力値であった場合、エラーメッセージを返却する
2.パスワードの取得を行う
2-1.パスワードの入力値のチェックを行う
2-1-1.入力値が存在しなかった場合、入力値が存在しない旨のエラーメッセージを返却する
2-1-2.入力値が不正な入力値であった場合、エラーメッセージを返却する
3.ユーザーテーブルより以下のSQLでユーザー情報の存在確認を行う
SQL）
対象カラム：ID、パスワード
対象テーブル：ユーザーテーブル
条件：ユーザーテーブルID == 取得値ID
ユーザーテーブルパスワード == 取得値パスワード
4.存在しなかった場合、画面へエラーメッセージを表示する
5.存在した場合、ホーム画面へ遷移する
記述例のような書き方にするメリット
- ステップ毎に記載してあるためコーディングの際に進捗がわかりやすい
- SQL等の条件等が明記されているため試験書作成の際にテストケースが作成しやすい
- 作業が途中で引き継ぎになった場合、次の作業者がどこから作業すれば良いか比較的明確
- ステップ毎に記載しているため設計者とプログラマで質問等のやり取りが行いやすくなる
注意点
- 実際はプロジェクト毎に記述のルールやテンプレートが存在するので基本的にはそちらに準拠するように記載してください。
- レビューアーにレビューしてもらい良好であると判断されても実際は考慮が漏れている可能性もあるためレビュー後も注意が必要です。
記述例のように詳細に記載すべき理由
そこまで工数を割けないと思われるかもしれませんが、設計書作成段階で工数を割き良質な設計書を作成できればそれ以降のコーディング、試験書作成において工数を削減する事が見込まれます。
将来的な工数削減を見据えて現在の工数を割く。いわば工数削減のための先行投資です。
最後に
今回記載した内容に関しては設計書を分かりやすくするための記述方法の一部に過ぎません。他にも分かりやすくする方法は多数あります。
また、「記述例の注意点」にも記載しましたがプロジェクト毎に記載の方法は異なりますのでこの記事はあくまでも参考程度にしていただければ幸いに思います。
Discussion