技術とか戦略とか

SIerで証券レガシーシステムを8年いじってからSESに転職した普通の文系SEによる技術ブログ。

システムの概要を示す設計書が本当に必要な設計書である

表題の通りですが、システム開発で本当に必要な設計書は、システムの概要を示す設計書です。
そのような設計書があれば、実装を知らない立場の人(例えば要件定義担当や上位の設計者)との意思疎通がスムーズになりますし、開発者を新たに向かい入れる時にも実装の内容をスムーズに理解してもらえるようになります。
 
----
 
例として、在庫確認モジュールを開発しているとします。
具体的な実装としては以下のイメージとします。
実際には、「:」の箇所に数行~数十行のコードが書かれているイメージです。
 
【実装イメージ】
// インプットのオブジェクトの生成(全商品リスト)

// アウトプットのオブジェクトの生成(要発注リスト、確認済リスト)

// 現時点の全商品リストの取得

// 商品の発注点の計算(全商品リストを更新)

 // 種類Aの商品の場合
 :
 :(複雑なビジネスロジック
 :
 // 種類Bの商品の場合
 :
 :(複雑なビジネスロジック
 :
 // 以下同じような処理
 :
 :
 :
 :
 :
 :
// 発注が必要かどうかの判定

 // もし必要なら要発注リストへ当該商品を出力
 :
// 全商品を確認済リストへ出力

// オブジェクトクローズ

 
----
 
良くない設計書の例としては、以下のようなものがあります。
(残念ながら、実務でも見かけることがあります)

ソースコードと1対1対応の設計書
 ソースコードを1行1行日本語に訳したような設計書は良くありません。
 そのような設計書は記述量が多くなり、
 作成するのも大変ですし、それを読んで内容を理解するのも大変です。
 また、日本語(自然言語)は意味が曖昧になりがちなので内容も不正確になります。
 更に、ソースコードに些末な変更を行う度に、
 設計書の更新も必要になるという問題もあります。
 (設計書の更新を忘れると、設計書を信用できなくなる)
 
・見た目だけで内容に乏しい設計書
 経験が浅く見様見真似で設計業務に当たっている場合、
 以下の絵のような見た目だけの内容に乏しい設計書を作成しがちです。
 (この例の絵は少し誇張しすぎですが)

f:id:akira2kun:20210718190255j:plain
 しかし、設計書はかっこ良い所を見せる資料ではなく、
 実装に直接的・間接的に関わる人と意思疎通を取るための資料なので、
 実装内容が早く正確に伝わればそれで良いです。
 どのような設計書を作れば良いかイメージが付きにくい場合は、
 現現場の既存の設計書や他現場の設計書を参考にしたり、
 先輩社員に聞いたりすると良いでしょう。
 
----
 
 システムの概要が早く正確に伝わる設計書が良い設計書です。
 例えば、以下のような処理概要を掴めるフローチャートは良い設計書です。

f:id:akira2kun:20210718190357j:plain

 このような設計書があれば、
 要件定義担当や上位の設計者が全体像をつかみやすくなり、
 レビュー(要件や全体の設計の観点から見て問題がないことの確認)が捗ります。
 また、新たに開発者を向かい入れる場合にも、
 モジュールの全体像を掴んでもらってから、
 必要に応じて細かい箇所を確認してもらうことができるようになります。