この記事では、基本設計フェーズで作成する各種のドキュメントの中で、特にビジネスロジックに関する基本設計書に関して、よりよいドキュメントを作成したい方のためのノウハウを提供します。
1. はじめに
1.1. 基本設計書は大切なドキュメント
「基本設計」という言葉は、ITシステムに関する仕事をされている方においては、知らない人がいないであろう言葉だと思います。
そしてこの基本設計における各種のドキュメント、特にビジネスロジックを記載した基本設計書（以下、基本設計書）は、業務を担当するユーザ側担当者（以下、ユーザ）とシステムを構築する設計担当者（以下、設計者）の心の架け橋となる、大切なドキュメントです。
1.2. うまくいかない基本設計
しかし世の中のシステム構築の現場では、この基本設計書がうまく書けていないがためにユーザと設計者の間で心が通わず、結果的に完成したシステムがユーザが予想していたものと違う！という事態が数多く発生していることかと思います。
本コラムでは、本来あるべき姿の基本設計書を正しく理解し、基本設計書に何を書き、どのようにしてイケてる基本設計書を書くか、という点について設計者の観点で述べたいと思います。
2. イケてる基本設計書って何？
2.1. 基本設計書は誰のもの？
基本設計書とは、（特にウォーターフォールモデルによる開発では）ユーザからしてみればそのシステムの仕様について口を出すことができる ”最後の砦” です。ここで問題があると、次にユーザが問題に気付けるのは結合テスト以降のタイミングとなるでしょう。
そんなユーザにとっての最後の砦である「基本設計書」って、誰のための何をするドキュメントなのでしょう？
システム開発に携わっている人には、こう答える人もいるかと思います。
「設計者や開発者が、仕様を理解してFIXさせるためのドキュメント」
こう答えた方は、基本設計書を通してユーザと心が通わないことがありませんでしょうか。
基本設計書は設計者が作成するため、基本設計書を前述のように位置付けていると、「IT専門家の目線」でドキュメントを書いてしまいがちになります。
そしてその結果、ユーザと心が通わないドキュメントが完成してしまうのです。
では、心を通わすためには、誰のための何をするドキュメントであるのが正解なのでしょうか。
筆者はこう思います。
「ユーザのための、ユーザの思い描くシステムであるかを確認するドキュメント」
基本設計書が用いられる状況も色々とあるため一概には言い切れないですが、基本設計時に「なんだかうまくいかないな・・・」となったときに立ち返ってみて、上記のことを思い浮かべていただければと思います。
2.2. イケてる基本設計書を書くには？
ユーザのためのイケてる基本設計は、以下のような書き方でなくてはなりません。
- (1) ユーザの読みやすい論理的な言葉で書く
- ユーザが読んだとき、理解できる言葉（論理的）で書きましょう。 技術的な専門用語を使うときは、ユーザがその言葉を理解あるかを確認し、理解がなければ事前に用語集等を整備しておきましょう。
- (2) 何のために何をする処理なのか、端的に書く
- 処理の概要として、その機能は業務の何を自動化し、結果としてどうなる処理なのか、5W1Hを意識して端的にまとめましょう。 長文を書いてしまうと、それだけでユーザは読む気をそがれてしまいます。
- (3) MECEで書く
- MECE という言葉があります。MECEとは、「漏れなくダブりなく」ということです。 分岐条件を書くときに、条件に漏れがあると、それは片手落ちの仕様となりますし、ダブりがあれば無駄なソースコードを生む原因になります。
- (4) わからないところをわかれ
- 設計者は、自分が業務の何が理解できていないのか、知りましょう。 そして、知らないことは知っている人、つまりユーザにしっかりと聞き、腹落ちさせましょう。 基本設計だけに限らず、システムを作るうえで当たり前、且つ最重要なことですね。
・・・まだまだ抽象的ですね。
では次に、イケてる基本設計書をどのように書くか、上記を踏まえて具体的に例を挙げて考えていきましょう。
3. イケてる基本設計書を作ろう
基本設計書には、少なくとも「処理概要」「プロセスフロー」「処理内容」を記載すると思います。
それぞれの部分で、何を書くか、そして良い例・悪い例を合わせて見ていきましょう
（ちなみに悪い例は、過去に筆者が見た基本設計書で実際にあったことです）
－処理概要－
処理概要は、その機能の行う処理について、論理的に5W1Hを意識して記載します。
例：社員マスタ管理画面の基本設計書
いかがでしょうか。悪い例では、当たり前のことしか書いておらず、概要の説明になっていません。
単なるマスタ登録処理においても、5W1Hを意識した内容を書くべきです。
－処理フロー－
処理フローは、処理を俯瞰的に把握し、文章だけで表現しきれない分岐処理等を理解するために記載します。
記載のポイントは数多くありますので、ポイントをまとめてみましょう。
＜処理フロー例１＞
| No. | 悪い例 | 良い例 |
|---|---|---|
| 1 | 初期処理が抽象的で追加情報が何もない | 初期処理は共通処理で定義済みであることを示している |
| 2 | 物理名で書かれているので何のテーブルかわからない | ユーザが分かる論理名で書いている |
| 3 | 矢印がなく、またCRUDもよくわからない | Inputのテーブルで、Readしていることが分かる |
| 4 | "Get"という英単語を使用しており分かりにくい | "取得"という言葉を使っており分かりやすい |
| 5 | !=0 というシステム的な表記が分からなく、且つNotが判定条件になっている | 取得件数のあり、なしと論理的に書いている |
| 6 | 正常な処理が横から出ている | 正常な処理が下方向に流れるように書いている |
| 7 | エラー処理で何をするのかわからない | エラー処理でメッセージを表示させることが分かる |
| 8 | エラー処理の後の線がない | エラーメッセージの後は、処理が終了していることが分かる |
＜処理フロー例２＞
| No. | 悪い例 | 良い例 |
|---|---|---|
| 9 | 正社員と契約社員しか分岐がない | 正社員、正社員以外とMECEに書かれている |
| 10 | 区分の値しか書かれておらず、意味が分からない。且つMECEか分からない | 論理名で書かれており、且つMECEになっている |
| 11 | ○○処理と××処理の縦位置が違い、同系統の処理であることが分からない | 同系統の処理で縦位置を揃えており、相関関係が分かりやすい |
| 12 | 次処理がフロー部品の上側から線が伸びている | 処理の流れが上から下に流れている |
| 13 | ソースコード記載に準拠して、IF~ELSEの連続でフローを書いている | 区分毎に処理が違うことが一見して理解できる |
| 14 | 同じような処理を続けているのに、Yes/Noが突然入れ替わっている | （同上） |
| 15 | 疑問、確認点が一切ないように見える | 不明点が何なのか明記されている |
| 全般 | ナンバリングがなく、処理内容と合わせて見ることができない | 各処理のポイントでナンバリングが付与されており、処理内容との紐づけができる |
上記を踏まえ、フロー図を書くときは以下を常に意識しましょう。
- 基本原則
- どう書けば読み手が読みやすく理解しやすいかを常に意識する
- フローは上から下、左から右に流す
- 共通処理やサブルーチンを有効活用する。
- 物理値で書かず、論理値で書く ※物理値を添えた一覧等を補足すると可読性UP！
- わかりにくければコメント追記して補足説明
- 不明点がどこで、何がわからないのかすぐ見えるように記載（赤文字にする等）
- 凡例を記載（結構忘れがち） ※上記例では省略しています。。。
- 処理毎にナンバリングを付ける ※後述の処理内容との紐づけに使います
- 分岐処理
- 分岐がMECEであること
- 分岐をプログラムロジックのように書かない
- 正常系・異常系の分岐は、正常系を縦に繋げ、異常系は横道へ
- Notを判定条件にし、それに対してYes/Noを判定分岐としない
- 複数ケースの分岐は、ひし形による分岐記載にこだわらず、可読性を優先させる
- エンジニア目線
- 比較演算子は、ユーザの理解できない "==","!=","<>" 等で書かない
- 言語依存の用語（Null、空文字など）を使わない。
－処理内容－
次に、処理フローの横に書かれる処理内容はどのように書くべきでしょうか。
上記処理フローに対する説明文を例としてみましょう。
＜処理内容例１＞
| No. | 悪い例 | 良い例 |
|---|---|---|
| 1 | ナンバリングがなく、処理フローとの相関性が分からない | 処理フローに対応したナンバリングを記載 |
| 2 | 初期処理を行うとだけ書いてあり、何をするのか不明 | 初期処理は共通処理で、別ドキュメントに記載していることが分かる |
| 3 | 物理テーブル名を書いており、また「社員を取得」するとか書いておらず不明瞭 | 論理テーブル名を書いており、なにをどのように処理するかを明記している |
| 4 | SQL構文を書いており、技術者しか理解できない | DB処理する部分を論理的に書いている |
| 5 | !=0 のように比較演算子を使用しており、よくわからない | 論理的な文章で書いている |
| 6 | エラー処理で何を行うのか明確にしていない | エラーメッセージを画面に表示することを明記している |
| 7 | ここだけ「行われます」とあり、ですます調が違う また、受動態の文章になっている |
ですます調が統一されており、能動態の文章で書いている |
＜処理内容例２＞
| No. | 悪い例 | 良い例 |
|---|---|---|
| 8 | IF分岐を整理しておらず、分岐の処理内容を把握しづらい 前述のNo.5と同様に、比較演算子を使用している |
分岐条件が整理されており、理解しやすい論理的な文章で書いている |
| 9 | 同一項目で「勤務形態」「勤怠形式」の表記揺れがある | 表記揺れがない |
| 10 | 区分値を物理値のみで書いており、その意味がわからない またOR条件をプログラム言語のように記載しており、技術者しか理解できない |
区分値を論理名で明記している AND条件、OR条件を論理的に整理しており、可読性が高い |
| 11 | 区分値毎の処理を行うのに、IF～ELSEをプログラミング的に書いており、俯瞰して把握しづらい | 区分値を表形式でわかりやすく整理している |
| 12 | 不明点、追記コメント等が一切ない | 確認点を赤字で記載し、追記コメントを記載している |
上記を踏まえ、処理内容を書くときは以下を常に意識しましょう。
- 基本原則
- 処理フローとナンバリングを揃え、どこで何をしているかを関連付ける
- どう書けば読み手が読みやすく理解しやすいかを常に意識する
（読み手はユーザのため、技術的な表現は極力使わない） - 文章で書きづらければ、表形式や図解を活用する
また、説明が多岐にわたったり省スペースでの表現が難しい場合は、別ファイルへ切り出す等の工夫をする - 段組みや文字色等、記載ルールを定めて記載する （独自ルールを作らない）
- 表記揺れが起こらぬよう注意する
- 文章表現
- 文章を簡潔に、且つ改行をうまく活用して書く
- 文章の入れ子に注意し、他の意味でとらえられることがない文章にする
- 「XXXされる」という受動系表現をせず、「XXXする」という文章で書く
※例えば「クリックされる」はシステムが主語になる。しかし「クリックする」であればユーザが主語となり、ユーザ目線となる
- ユーザ目線
- SQL構文をそのまま書かない
- 物理値や比較演算子を使わず、論理値を用いて文章表現で記載する
4. さいごに
いかがでしょうか。
イケてる基本設計書を書くことができれば、それだけレビュー指摘による手戻りを少なくすることができ、結果的に必要となる工数を削減することができます。
慣れるまでは気を付けるところが多く、手間を感じるかもしれませんが、それがプロジェクトチームの文化として定着し、ひいては会社全体の文化として定着すれば、それが普通のこと、当たり前のことになると思います。
読んでいただいた中で賛否両論があるかと存じますが、ひとつの例としてとらえていただき、その中で自分（自分達）の正解のスタイルを見付けていただければ幸いです。
大事なのは、ドキュメントは「いつか知らない人が見る（かもしれない）」ということを常に念頭におくこと。
そしてよいドキュメントとは、
「誰が読んでも読みやすく、そして正しく同じ認識を得られるドキュメント」
だと思います。