はじめに

みなさんは設計書を書く際に気を付けていることはありますか？
今回は私が最近設計書レビューをしてて感じる事について記載していこうと思います。

その設計書ただのメモ書きになってませんか？

何故この記事を書こうと思ったのかですが、
「その設計書はあなたがコーディングをするためだけのものじゃない」
ということをお伝えしたいためになります。

では、具体的に何を意識するのか。

コーダーが何をどのように実装したいのか理解しやすい内容とする。
- 設計を担当したものを自分が作るとは限りません。
保守・運用を行う際にどのような造りになっているのか分かりやすい内容とする。
- 開発を行ったシステムを同じ人がそのまま保守・運用を行っていくとは限りません。

要するに、他人が見るドキュメントだということを意識してほしいということになります。

自分が開発を行うためだけのものではなく、
チームとして開発～保守・運用を行うドキュメントであることを意識する。

次の項では具体的に何を書くべきかについて記載していきます。
（具体的にと言いつつ抽象的な気もしなくもない・・・）

基本設計では何を書くのか

基本設計では要件定義をもとにシステムとして何を実現したいのかを記載していきましょう。
大まかにまとめると下記三点を意識できればよいと思います。

正常系の動作
バリデーション
異常系の動作

この中で特に書かれてないと感じるのは異常系の動作です。
以下の三点は最低限基本設計で検討しておけるとよいと思います。

エラーログの出力内容
ユーザにどのように通知するか
- 画面に表示するメッセージの出力方法や、バッチであればメールを送信する等
リカバリをどのように行うか

エラーが起きた際にどのように対応するかをしっかり検討しておく。

詳細設計では何を書くのか

詳細設計では各モジュールの処理内容や関連性を明確にしましょう。
その上で書かれてないなと感じる事は下記三点です。

共通化
どのようなライブラリを使用する想定なのか
モジュール同士の関連性

詳細設計において設計者から感じることは
「コーディングする際に考えればいいや」
ということです。

自分がコーディングするのであればそれでも何とかなるかもしれません。
しかし、その記載レベルだとほぼ必ずと言っていいほどコーダーから質問が飛んできます。
（質問がない場合は全然違うものができたりします・・・。）
せっかく詳細設計書を書いたにもかかわらずそこでコミュニケーションに時間を取られるのはもったいないですよね。
コーダーが迷子にならないように各モジュールで実装するべき内容を明確に記載しましょう。

誰がコーディングしてもコーディング内容に大きな相違が起きないレベルで記載する。

余談

設計について記載してきましたが、コーディングの際のコメントも同様になります。
美しいソース（保守・改修・運用しやすいソース）というのはコメントも含めて完成するものだと思います。
得てして開発は時間が足りなくなりがちで、蔑ろになってしまう部分ではありますが、
そこで書いたあなたのコメントで救われる命があります（笑）

まとめ

初めてこの様な記事を書かせていただきましたが、
「設計書に限らず各ドキュメントは他人が見ることを想定した記述レベルで書く」
ということがお伝えできていれば幸いです。
自分が何を表現したいか分からないドキュメントであれば他人は絶対に分かりません（苦笑）
どこまで書けばいいのか最初は難しいと思いますが、その際は周りの諸先輩方を頼りながら分かりやすいドキュメントを作成していきましょう。