内部用の設計書の書き方

はじめに

こんな人向けの記事。

  • 最近 設計書を書くようになったが、レビューで指摘が多い。
  • 設計書ができたはいいが、何に使うのかよく分からないものになってしまった。
  • 伝えたいことが伝わらない。Aのつもりで書いたのにBと勘違いされる。

また、ここでの "設計書" は以下のものを想定。

  • 内部で使うもの(納品物には含まれない)
  • 目的
    • モブプロなどでチームの意識合わせを行う。
    • レビューアとの認識違いによる、コードレビュー時の指摘を減らすため。
  • 既存のコードを変更する際に、どんな変更をするかを記載したもの(改造設計書など)
  • 既存のスパゲッティコードを読み解いて、どんな設計になっているかを調査した結果
    • 前述の改造設計のために実施。
    • プログラム設計書を読めばわかる?ない or 現状と合っていないから作るんです。
  • 基本的にMarkdownを使って記述したもの
    • 頻繁に変更する予定で、そのとき自動計算があると楽ならエクセル。

全体の手順

  1. "目的"、"読み手"、"必ず伝えたいこと" を明確にする
  2. 目次の作成(項目が多くなるなら)
  3. 中身を書く
  4. 推敲
  5. レビュー

1. "目的"、"読み手"、"必ず伝えたいこと" を明確にする

  • 何のためにその設計書を作るのか?
  • 設計書を読むのは誰なのか?(レビューアを除く)
  • 設計書で必ず伝えたいことは何か?

これが適当だと、できるものも適当なものになってしまう。

2. 目次の作成

基本的には以下が必要。

  1. タイトル
  2. 概要
  3. 目的
  4. メイン(書くものによって異なる)
  5. まとめ

この時点でレビューアに確認するのもいい。
間違えていた場合、戻り作業が少なく済む。

3. 中身を書く

文章

  • 1文をながーくするのは避ける。
    • 「○○は○○することにより○○から○○を○○でき、また...」とずらずらと長い文を書いてしまうと読みにくくてしょうがない。
  • 箇条書きにするなら、同じレベルには同じことを書く。
    • 「箇条書きで書いているのに、中身は1文ごとに改行したのと変わらない」では箇条書きの意味がない。

図表

  • メインとなるものが埋もれそうなら、印などをつけて目立たたさせる。
  • サンプルとして示したのか、特殊なのかを分かるようにする。
  • シーケンス図、クラス図、フローチャートなどを書くならmermaidがおすすめ。テキストベースで書けるため、Gitなどで差分が見やすい。
    • 先にレビューアに使っていいか確認を取ること
  • フローチャートなどの場合、どの形がどういう意味か分かりにくくなる。先に凡例を書いておくといい。
    • 標準で決まっている規格があるなら、それを使うといい。

4. 推敲

  • 誤字脱字はいくら見直してもよくある。
  • 先にチェックリストを作っておいて、それを確認するのもいい。
    • 内容は、前回までにレビューで指摘されたこととか。
    • どんどん増えてそのうち見る気を失うので、ときどき整理したほうがいい。

5. レビュー

  • 単なる誤記でない限り「レビューアがAと言ったのでAに直した」というのはよくない。
    • ものによってはレビューアの気分で直す羽目になる。
    • 何故直すのか理解する必要がある。