どんなことに注意して書けばいいんだろう？
こんにちは、古賀です！
本記事では、
はてな
- 詳細設計書は書き過ぎてはいけない！
- 詳細設計書を書く時のポイント！
- 詳細設計書のオススメ作成法！
について、お話します！
詳細設計書を書くことが苦手で、
「なかなか書けない。。」という方もいますが、
今回はその逆で「書き過ぎ」てしまっている方にフォーカスしてお話します！
「なぜ詳細設計書を書き過ぎてはいけないのか？」
「詳細設計書を書く時のポイント」と、
限定的ではありますが「オススメ作成方法」について紹介させて頂きます！
自己紹介が遅れましたが、
わたしは大学卒業後、上場IT企業に就職し、プログラマー、システムエンジニアとして
約１０年間働きまして、現在フリーランスをしております。
プロフィールの詳細はこちらです。
-
-
プロフィール
こんにちは、古賀正雄です。現在３６歳です。 簡単ではありますが、こちらのページで自己紹介とこのブログについてお話します。 高校時代 学生時代は主に野球をしていました。 進学先の高校も野球で選びました。 ...
続きを見る
詳細設計については以下の記事でもお話しています。
今回は以下の記事を補足する内容になりますので、こちらもご参考ください！
-
-
詳細設計書が書けない？仕様書が書けなくても最低限やるべきこと！
基本設計を終えて、次は詳細設計。 だけど詳細設計書ってうまく書けないんだよな。。 プログラムもあまり経験してこなかったし。 いったい何を書けばいいのか。。 こんにちは、古賀 ...
続きを見る
-
-
プログラマーから信頼されるシステムエンジニアへ！詳細設計で配慮すべき３つのこと！
なんだかプログラマーから冷たい視線を感じるなぁ。。 確かに設計書の間違い何回もしてるしなぁ。。 でもプログラマーの方だって、バグ出してるからおあいこだろ！ こんにちは、古賀 ...
続きを見る
※YouTubeに同内容を公開しております。
詳細設計書を書き過ぎてはいけない理由！
基本的に「詳細設計書を書く」ことを苦手にしている方が多いので、
書き過ぎくらいがちょうど良いかもしれませんが、
稀にそれを超えて「書き過ぎ」てしまう場合があります。
また、
「もっとどうやって実現するかまで書いて！」
と指示される場合もあります。
まず、ここで言う「書き過ぎ」についてですが、
注意ポイント
「プログラミングっぽく作り方を全て書いてしまう」
ことです。
では、なぜ「プログラミングっぽく全て書き過ぎてはいけない」のかと言うと、
- 何をしているのか分からなくなる
- 修正が発生した時に大変
- 実現できない可能性がある
からです。
詳細設計書を読んでも何をしているか分からない
別の記事でもお話しましたが、詳細設計書の役割は、
- プログラマーが詳細設計を見ながら、プログラムを作成するため
- 詳細設計を見ながら、単体テストを行うため
- 運用保守時に詳細設計を見ながら、調査を行うため
この３つですが、最後の３つ目
「運用保守時に詳細設計を見ながら、調査を行うため」
が、とても重要です！
その時、詳細設計書がプログラムっぽく書かれていたら、調査が大変です。
むしろプログラムを直接見た方が良くなります。
なので、詳細設計書を見ただけで、
「どんな処理がされているか？」
がわかるように書いておく必要があります。
詳細設計書の修正が大変
詳細設計書を作成した後は、実際にプログラム開発を進めていきますが、
開発中でも、テスト中でも、保守中でも、
詳細設計書の修正が必要になる場面が必ずと言っていいほどあります。
その時にプログラムっぽく書かれていると、
些細なコード変更の場合でも、詳細設計の修正をしなくてはなりません。
これはかなり「めんどくさい」です！
やがて詳細設計書がおきざりになって、プログラムと設計書が一致しなくなり、
運用保守中で調査が発生した場合は、プログラムを直接見るしかなくなります。
これを防ぐためにも「書き過ぎ」に注意しましょう！
詳細設計書の内容で実現できるか分からない！
せっかく細かく詳細設計を書いたのに、プログラムを書いた時に、
その設計内容で実現できない可能性があります。
プログラムの「規約」であったり、
使用する「言語」や「フレームワーク」、
様々なことが原因で、設計内容では実現できないと判明することがあります。
せっかく書いた内容が無駄になってしまう可能性があるので、
プログラムっぽく書き過ぎないようにしましょう！
また、こういった「どう実現するか？」の部分は、
「プログラム開発時に考えた方が早い！」
場合も多いです。
色々とコードを書いて、試しながら実現方法を探すこともできるので、
書き過ぎに注意しましょう！
以上が「プログラミングっぽく全て書き過ぎてはいけない」理由です！
詳細設計書を書く時のポイント！
「書き過ぎてしまうと、良いことばかりではない」というのが多少伝わったと思います。
「では、どこまで書けば？」と思われたと思うので、
詳細設計を書くポイントを少しお話します！
まずざっくりポイントを言いますと、
ポイント
「目的」である基本設計の内容を補足して「手段」や「材料」をシステム語で書く！
これを意識しましょう！
そして「手段」の部分を書き過ぎないようしましょう！
先程、「実現方法まで書かない方が良い」と言いましたが、
「詳細設計書には入口と出口だけ書いて、出口までのルートはプログラム開発時に行う」
という感じです！
これならば、調査を行う時も必要な情報だけ書かれているので、かなり見やすくなり、
運用保守中も詳細設計書がかなり役立ってくれます！
ただ、これだけだとざっくり過ぎて伝わらないと思うので、少し具体例を挙げます！
詳細設計書を書くポイント 例１
１つ目の例ですが、基本設計書に、
「請求書発行後は売上伝票の修正は不可」
と記載してあったら、詳細設計書は、
売上伝票番号入力時、
請求書発行後（売上データ.請求書発行フラグ＝１ Key:入力.売上伝票番号）の場合、
エラーメッセージを表示して処理を終了する。
という感じになります。
基本設計書に書いてある目的に対して、
- 「売上伝票を入力した時」
- 「請求書発行のシステム上の判断基準」
- 「エラーメッセージ表示」
といった、手段やアクションをシステム語で表現しています。
ここで、売上データを取得する詳細なSQL文まで書く必要はありません。
対象データや、取得するための材料は既に記載しているので、
わざわざ「SELECT～」とプログラム的なことは書かなくても大丈夫です。
「出口までのルート」はプログラム時に考えれば十分です！
詳細設計書を書くポイント 例２
もう１つ簡単な例を挙げます。
「売上金額の合計を表示」
という内容を詳細設計書に反映させると、
「売上明細.売上金額を売上伝票番号で集計して画面に表示」
だけでＯＫです。
「ループして売上金額を合計する」とか、
「データ取得時にSUMする」とか、実現方法までは書かなくて大丈夫です！
合計の取得方法は１つではありません。
その取得方法は実際にプログラムを作成するプログラマー側で判断した方が良いです。
ただし、システム的な判断基準「材料」は必ず記載しておきましょう。
それが書かれていないとプログラムを「どう作ったら良いのか？」分からないので、
区分が１の時とか、明確なシステムの判断基準は忘れずに書きましょう！
それだけ書いてあったら十分です！
「入口」と「出口」だけ。これを意識しましょう！
詳細設計書のオススメ作成方法！
使える場面が限られているので、かなり限定的ですが、
オススメの詳細設計書作成方法は、
「プログラム作成後に詳細設計書を作成する」
です！
「えっ！？詳細設計の役割を放棄してるじゃん！」
と思われるかと思いますが、最終的に行きつく答えは「後で作成」です！
先程お話した通り、詳細設計書の修正作業はかなりめんどくさいんです。。
それを「後で作成」することで、少なくとも開発作業中の修正作業がなくなって、
時間の節約に繋がります。
また、プログラム作成後に設計書を書くことで、
これも先程お話した通り、
「無駄な部分は省いて、必要な情報だけ残っている」
詳細設計にすることができます。
実物が完成している状態なので、内容の良い設計がスラスラ書けます！
実際に詳細設計工程を丁寧に行わない現場も少なくないです。
詳細設計や開発工程は、お客さんと直接やり取りする工程ではないので、
「詳細設計を終えてから開発工程に入る」
というウォーターフォールのルールに縛られずに、比較的自由が利く工程です。
ウォーターフォールのやり方が悪いというわけではありませんが、
詳細設計、開発工程だけ部分的にアジャイルを取り入れるのもアリではないかと思います。
もちろん詳細設計がなくても開発ができるプログラマーがいて初めて成り立つやり方なので、
チーム構成によるところもあります。
強いプログラマーがいるチームであれば、検討してみる価値はあると思います！
まとめ：詳細設計書は書き過ぎない！
ここまでの話をまとめます。
まとめ
詳細設計書は書き過ぎ注意！
理由は、
- 何をしているのか分からなくなる
- 修正が発生した時に大変
- 実現できない可能性がある
から！
詳細設計を書く上でのポイントは、
「目的」である基本設計の内容を補足して「手段」や「材料」をシステム語で書く！
「入口と出口だけ書いて、出口までのルートはプログラム開発時に行う」
オススメの詳細設計作成方法は、
「プログラム作成後に詳細設計書を作成する！」
わたしがまだプログラマーになりたてだった頃は、
周りがそこまで丁寧に詳細設計を書く文化ではなかったため、
詳細設計がない状態で、プログラムを作成することがよくありました。
そのおかげもあって、詳細設計書がなくてもプログラムを作成することができるようになったり、
時には自分で詳細設計を書いて、自分でプログラムをすることもありました。
そんなやり方を続けていくうちに、
「詳細設計を書いた後にプログラムを作る」ことが、
なんか無駄だなと言うか「二度手間感」を感じるようになりました。
一度プログラムを作成した後に詳細設計書を後で書くようにしたら、
見積工数より大分早く作業を終えることができました。
もし、現在プログラマーをしていて、
「詳細設計がないとプログラムができない！」という方は、
詳細設計がなくても、プログラム開発ができるようになりましょう！
そういう人材には価値がありますし、
上流工程に挑戦したい時も、そのスキルが役立ちます！
「書き過ぎない詳細設計書」も書くことができるようになります！
良い詳細設計を書いて、プロジェクトを成功させましょう！
