📄
内部用の設計書の書き方
はじめに
こんな人向けの記事。
- 最近 設計書を書くようになったが、レビューで指摘が多い。
- 設計書ができたはいいが、何に使うのかよく分からないものになってしまった。
- 伝えたいことが伝わらない。Aのつもりで書いたのにBと勘違いされる。
また、ここでの "設計書" は以下のものを想定。
- 内部で使うもの(納品物には含まれない)
- 目的
- モブプロなどでチームの意識合わせを行う。
- レビューアとの認識違いによる、コードレビュー時の指摘を減らすため。
- 既存のコードを変更する際に、どんな変更をするかを記載したもの(改造設計書など)
- 既存の
スパゲッティコードを読み解いて、どんな設計になっているかを調査した結果- 前述の改造設計のために実施。
- プログラム設計書を読めばわかる？ない or 現状と合っていないから作るんです。
- 基本的にMarkdownを使って記述したもの
- 頻繁に変更する予定で、そのとき自動計算があると楽ならエクセル。
全体の手順
- "目的"、"読み手"、"必ず伝えたいこと" を明確にする
- 目次の作成(項目が多くなるなら)
- 中身を書く
- 推敲
- レビュー
1. "目的"、"読み手"、"必ず伝えたいこと" を明確にする
- 何のためにその設計書を作るのか？
- 設計書を読むのは誰なのか？(レビューアを除く)
- 設計書で必ず伝えたいことは何か？
これが適当だと、できるものも適当なものになってしまう。
2. 目次の作成
基本的には以下が必要。
- タイトル
- 概要
- 目的
- メイン(書くものによって異なる)
- まとめ
この時点でレビューアに確認するのもいい。
間違えていた場合、戻り作業が少なく済む。
3. 中身を書く
文章
- 1文をながーくするのは避ける。
- 「○○は○○することにより○○から○○を○○でき、また...」とずらずらと長い文を書いてしまうと読みにくくてしょうがない。
- 箇条書きにするなら、同じレベルには同じことを書く。
- 「箇条書きで書いているのに、中身は1文ごとに改行したのと変わらない」では箇条書きの意味がない。
図表
- メインとなるものが埋もれそうなら、印などをつけて目立たたさせる。
- サンプルとして示したのか、特殊なのかを分かるようにする。
- シーケンス図、クラス図、フローチャートなどを書くならmermaidがおすすめ。テキストベースで書けるため、Gitなどで差分が見やすい。
- 先にレビューアに使っていいか確認を取ること
- フローチャートなどの場合、どの形がどういう意味か分かりにくくなる。先に凡例を書いておくといい。
- 標準で決まっている規格があるなら、それを使うといい。
4. 推敲
- 誤字脱字はいくら見直してもよくある。
- 先にチェックリストを作っておいて、それを確認するのもいい。
- 内容は、前回までにレビューで指摘されたこととか。
- どんどん増えてそのうち見る気を失うので、ときどき整理したほうがいい。
5. レビュー
- 単なる誤記でない限り「レビューアがAと言ったのでAに直した」というのはよくない。
- ものによってはレビューアの気分で直す羽目になる。
- 何故直すのか理解する必要がある。
Discussion