##目的
現場で詳細設計を作成する機会が増えた為、「詳細設計の役割って何？」「分かりやすい詳細設計書の書き方は？」ということをまとめて、自分の理解を深めると共に、研修を終えて現場に出たエンジニアの方に少しでも詳細設計についての知識を共有できればと思い投稿しました。
##詳細設計とは
システム開発の上流工程は
「要件定義」→「基本設計」→「詳細設計」の流れに従って進められていきます。
その中で詳細設計は
「基本設計で決められた動きをどうやって実現するかを決める」
役割を担っています。
要するに前工程である「要件定義」「基本設計」までで決められたシステムの実現の為に「どう実装するか」というところまで落とし込む工程と言えます。
故に、詳細設計を見る人間はお客様ではなくプログラマーであり、「分かりやすい詳細設計」＝「実装しやすい設計書」とも考えられます。
##分かりやすい詳細設計の作成方法
ポイントは
・認識のズレがないように
・求められている機能を実現
できる設計書を作ることだと思っています。
よくあるプログラミングバグで、受け取る値を間違えたり、値の送り先を間違えたりといった、プログラミングの知識以外のところでつまづくことがあります。
どんなエンジニアが見ても
「何」を「どうする？」
ということが分かるような設計書を作ることが大切です。
##じゃあ具体的に何を注意するのよ？
はい、ここからが本題です。
詳細設計はエンジニアがプログラミングしやすいように作成することが大切なんだなーと何となく分かったところで、じゃあ具体的に何をすれば良いのか分からないですよね。
ここからはぼくが実際に現場に出て意識した方がいい事、大切だと思った事をまとめていきます。
###当該文書の作成目的を文頭に宣言する
プログラマーが実装する際に参照する資料を探す時間を短くするため
（例）「本書では◯◯機能の仕様について記載する」のように目的を明確化する。
###簡潔な文章を
長々とした文章は分かりにくくなりがち。なるべく短い文章で分かりやすく表現することで認識のズレを回避する。
（例）文章は30字から40字程度に収まるように表現する。
###図の使用
プログラムの動きなど、文章のみでは理解しづらいものはフロー図を作成したり視覚的に理解できるような設計だと親切。
（例）エクセルであればフロー図を記載してあるシートを作成する。
###表の使用
条件分岐などは表を使うことでより分かりやすくなる。
（例）「分岐については以下を参照。」と記載して表を作成する。
###用語の統一
同じ機能、同じ概念は、一言一句同じ用語を使う。同じことを別の用語で記載すると認識のズレに繋がる。
（例）過去案件の設計書から用語を拾う。用語がまとめた資料を作成する。
###造語をしない
プロジェクト内で共通の概念であれば、既に使われている表現を使う。
当該文書内に閉じた概念で、自分で作り出した用語であれば、その定義の項を作り、明確に記載する。
（例）
〇〇〇〇〇（注1）
文末に
（注1）造語の説明を記載
等
###コピペを上手く使う
表記ミスをなくすためにキーボードでの手打ちをなるべくしない。
（例）
設計書にＤＢのテーブル名を記載するときは論理設計書からコピペする。
###レビューを受ける
設計書が完成したらチームリーダー等、第三者にレビューを受ける。
他人から見て「どういうこと？」と思われる箇所の指摘をしてもらうとなお良し。
##まとめ
実際に現場に出ると、プログラミングの知識不足によるミスや時間ロスと同じくらい設計書を読み解くのに時間がかかることがあります。知識は勉強したり仕事をしていくうちに覚えていけばいいことですが、それ以外のところで掛かる時間を減らせるような詳細設計書を作成する意識が大切だと思う今日この頃でありました。