【設計書作成】開発者が喜ぶ！詳細設計書の粒度と書き方ガイド
2025年1月入社のT.Nと申します。
今回は設計と製造を担当していた私が開発者から喜ばれる、詳細設計の書き方を記事にしました。
今後、詳細設計を書く際に、参考にしていただければと思います。
■詳細設計を書く前に
前提として、詳細設計とは基本設計の内容を詳細に記載するかつ、開発者側に寄って記載するものです。
そのため、基本設計の内容を完璧に理解した状態で詳細設計の作成を始めましょう。
基本設計で理解できていない箇所があれば、すぐに設計者に質問しましょう。
思い込みや予想で詳細設計を書いてしまうと、製造後に手戻りが発生し、
最悪の場合作り直しになる可能性もあります。
そうならないためにも、予め基本設計は完璧に理解してから取り掛かりましょう。
■詳細設計の書き方
現場によってフォーマットが違うため、自分の現場に合わせて作成して下さい。
今回は私が実際に現場で使用していた詳細設計をベースに進めさせて頂きます。
今回ベースとする詳細設計はパッケージのアドオン機能開発（機能の追加）になります。
①処理画面の作成
実際に製造した場合、どんな使用方法なのか、どんな結果になるかの画面を作成します。
画面は大きく分けて、【実行前】【実行中】【実行後】の3つを用意します。
このとき画面だけじゃなく、上に説明文を付ける事が大事です。
画面を出すことで、開発者は最終的な成果物のイメージが付くと思います。
私が製造していた際に、画面の内容から既存システムの流用が可能だと判断し、
工数を削減できました。
また、画面の実物がない場合(1から製造する場合)は大体のイメージ図でよいと思います。
(記載例)
【実行前】
「〇〇にメニューを用意し、メニューを押下することで実行」
(実行前画面)
【実行中】
「実行中と記載されているメッセージボックスを出力しておく」
「メッセージボックス内にキャンセルボタンを用意する。押下された場合、キャンセル処理」
(実行中画面)
【実行後】
「処理結果をメッセージボックスに出力する。」
(実行後画面)
②処理フローの作成
一般的なフローチャートを作成します。
この後、処理詳細を書く時に自分で確認することも出来るため、細かく書いて損はないと思います。
フローチャートの作成方法として、一度大枠を作ってから細分化させていくと簡単に作成できると思います。
最終的に作成したフローチャートは、枠のサイズ、文字の大きさ、配置場所(左右中央揃え)を揃えるようにしましょう。
フローチャートを丁寧に書くことで、開発者側は〇〇処理の前に何が必要かなど、処理のイメージが付いていきます。
逆にフローチャートの説明が雑になってしまうと、何がしたいのか伝わりません。
※何がしたいかわからない詳細設計は、詳細設計としての意味を成していないと言えます。
記載例として、簡単な処理のフローチャートを書きます。
どんな処理か考えてみて下さい。
(悪い記載例)
(良い記載例)
答えは「テキストファイルをコピーする処理」でした。
上記の例は大袈裟ですが、見やすさ、処理の理解度が全然違うと思います。
悪い例だと、「ファイルの取得」となっているため、本来テキストファイルをコピーするはずが、
開発者はCSVファイルやExcelファイルの場合でもコピーしてしまうかもしれません。
他にもファイルが存在しない場合やコピー処理に失敗した場合についての処理が記載されていないため、開発者は設計者に対して仕様確認する必要があります。
最悪の場合、ファイルが存在するか確認していないため、存在しないファイルをコピーしようとしてバグになる可能性があります。
恐らく単体テスト時に気づいて修正することになりますが、開発者側は手戻りが発生します。
このようなことを防ぐためにも、処理フローは丁寧に、詳細に書くと良いでしょう。
③処理詳細
ここでは開発者にどんな処理を作ってもらうか詳細に記載する必要があります。
主に処理の流れ、どの関数を使用するかなどを記載しましょう。
1.関数の書き方
使用する関数を記載することで、開発者と設計者の認識のズレがなくなります。
関数の作成時に必要なのは、以下の6点です。
※関数作成の際には、命名規則など現場のコーディング規約に則って作成して下さい。
・関数名
・引数名
・データ型
・IN/OUT
・引数の説明
・戻り値
この6点を表でまとめると見やすくなるためオススメします。
(関数の書き方例)
2.全体の処理の書き方
全体の処理を書く時に大切なのはインデントを変えることです。
膨大な処理の中で分岐処理やループ処理を記載する時に、
インデントを増やすことで、どこの処理にいるのかがすぐにわかります。
(処理詳細の記載例)
記載例として「②処理フローの作成」で使用した記載例の処理詳細を作りました。
処理に項番を振り、インデントを意識して作成したため、見やすいかと思います。
ここまで記載されていれば、恐らく開発者も問題なく製造できると思います。
今回は開発者が喜ぶ詳細設計書を書かせて頂きました。
個人的に詳細設計は開発するうえで、一番大切だと思っています。
今後、詳細設計を書く場合、本記事の内容を少しだけでも思い出していただけると幸いです。
