【設計書作成のポイント】：開発者目線からの設計書のポイント
2025年1月に入社したT.Nと申します。
前職でもSES会社に所属しており、約3年開発の現場に参画しておりました。
今回は基本設計から詳細設計までで大切にしていた内容を踏まえ、
開発者目線も含めながら記事を作成することにしました。
■基本設計での作業内容とポイント
◯作業内容
お客様と打ち合わせし、今後どんな機能が必要になるか、
現状の設定から変更したい点はあるかなどを伺い、
それに伴った機能の追加/改修を相談しながら仕様書を作成します。
ここでのポイントは以下の3つになります。
・お客様の想定している機能になっていること
・前提条件を決めること
・機能の背景を知ること
◯作業ポイント
・「お客様が想定している機能になっていること」
簡単なイメージ図等を作成し認識齟齬が起こらないようにします。
ここの認識が誤っていると後々仕様変更やクレーム等のトラブルの原因になってしまいます。
(開発者コメント)開発している途中に仕様変更が多いと期限が間に合わなかったり、
品質が落ちることが考えられるため、最重要ポイントだと思います。
・「前提条件を決めること」
前提条件を決めることで、今後の対応(概要設計～テスト)での開発工数を削減できます。
決めた結果は随時基本設計に記載して誤りがないか確認することが大切です。
(開発者コメント)テストデータの作成や、テスト実施などの時間が不要になるため
その分、期限が前倒しにできるのはメリットだと思います。
ただ前提条件が多過ぎると汎用性が落ちるため、リリースした後に仕様変更が発生するかも。。
・「機能の背景を知ること」
どんな機能なのかを開発者に説明する際に、お客様の事情と機能概要を伝えられると、
「〇〇とか必要では？」など自分が想定していなかった観点で再度認識が合わせられ、
より品質の良い機能になるため、ただ機能を作るだけではなく、作る背景を知ることが大切です。
(開発者コメント)エラーが発生した際のメッセージ内容を詳細に決めておくと、
エラーがお客様側で発生した際、何故エラーが発生したのかなどを調査しやすくなるため、
どんなユーザーが使用するかも知っておくと良いかもしれません。
■概要設計での作業内容とポイント
◯作業内容
基本設計よりもう少し開発者目線に合わせて記載します。
状況に応じてお客様側にもお渡しする必要があるので、
内容はわかりやすく丁寧に記載する必要があります。
ここでのポイントは以下の2つになります。
・処理の流れがわかること
・機能のイメージ図
※概要設計は現場によって、ある場合とない場合があります。
◯作業ポイント
・処理の流れがわかること
基本設計の段階で機能の概要は伝わっているため、
その機能をどう実現できるかを処理フローなどで記載し、
開発者に「ここで〇〇処理して欲しい」が伝わる仕様書にすることで、
製造する内容と仕様書で乖離が起きないようにします。
(開発者コメント)実際に処理の流れが記載されていないと、
製造したあとに「〇〇処理の前にチェック処理して欲しかった」など手戻り発生の可能性が
考えられるため、ここで認識を合わせておきたい！
・機能のイメージ図
基本設計時に文字で記載していた箇所を図で表現することで、より具体的に
データの流れや、最終的な完成形がわかると開発者とお客様の間で乖離が発生しづらくなります。
(開発者コメント)実際に基本設計書の文字と説明だけでは誤った認識していることも
少なくないので、製造が始まる前に再確認できるのでイメージ図が多いと助かります。
ただ、大きな機能で大量のイメージ図だと見る方が混乱するので、適当な量で記載しましょう！
■詳細設計での作業内容とポイント
◯作業内容
概要設計から詳細に開発者目線で記載する。
開発者側は詳細設計を見て製造するため、 処理の流れは詳細に記載し、
処理分岐なども考えて作成しましょう。
ここでのポイントは以下の2つになります。
・予期せぬ動作を考えること
・関数、引数の文言統一化
◯作業ポイント
・予期せぬ動作を考えること
詳細設計を確認しながら製造しますが、使用する関数によっては
バグが発生し、異常終了してしまいます。(最悪の場合データベースが落ちることも。。)
そうしたものを防ぐため、考えられるパターンを記載しておくことで、
何かあった場合でも正常に終了できます。
(開発者コメント)実際に異常終了したパターンがあったので紹介します。
バグ内容：ファイルをコピーしようとしたがコピー元が存在しない。
対象方法：コピーの前にファイルが存在するか確認する。
ファイルが存在したら→コピー、存在しなかったら→コピーしない
上記のエラーが発生しないような分岐処理を考えて作成すると良いと思います！
・関数、引数の文言統一化
製造では、関数に対する引数を設定することが多いと思われます。
例えば、ファイルをコピーする場合、関数に「コピーする」を記載し、引数に「コピー元」「コピー先」を指定することで、関数が正常に動きコピーが完了します。
上記のコピー関数を複数回しようするときに、1回目の引数で「コピー元ファイルの〇〇」「コピー先ファイルの〇〇」と指定しているいるが、2回目の引数では「コピー元」「コピー先」しか記載されていない場合、何に対してのコピーかわからないので、製造時に開発者が困ってしまいます。
そのため、詳細設計の作成時に予め自分でルールを決めておくとセルフチェックが簡単になります。
(開発者コメント)詳細設計を基に製造するため、関数と引数が非常に大事になります。
製造時にどの関数を使用するかを選定していると、その分だけ工数が掛かるので、
できるだけ詳細に記載して貰えると、製造以降の作業もスムーズに進みます！
設計書を作成する時は、「誰が見るか」「どんな情報が必要か」を気にして書いてみましょう！
今後設計書を書くときに役に立つことがあれば幸いです！
