システム設計の基礎：外部設計で作るべきドキュメントを考える

システム設計の基礎を学ぶ研修に会社のお金で行かせてもらったので、成果を書きます。

今回のテーマ

外部設計で作るべきドキュメントとはなにか？

研修の内容を受けて、外部設計段階で作成する一般的なドキュメントをまとめました。
それに対し、自分の開発チームがいま作っている資料を一般的なドキュメントの内容と比較・対応させて、外部設計にどんな資料が必要なのか考えました。

設計の前に：要件定義の確認

要件定義のアウトプットとして作成されるドキュメントは以下のようなものがある。

  • データフロー図（DFD）
  • 業務フロー図

うちだと、要件を文章や図で書いたものと業務フロー図がサービス仕様書に表現されているはず。このサービス仕様書を最初のインプットとして外部設計を作成し、業務設計担当者との認識を合わせていく。

まずは要件定義の確認、サービス仕様書を読む。チームで読み合わせとかすると良い。足りていない部分があれば要件定義した人に聞いてみる。

特に非機能要件、性能やSLAは設計に影響するので注意。
要件に書ききれていない非機能要件を聞き出せるのが良いエンジニアとのこと。

外部設計資料の一覧（一般）

世の中にはいろんなドキュメントがある
研修で習った各ドキュメントの名称と、表現したいことを簡単にまとめる。

コンテキスト図
  • 開発領域、スコープ
  • 関連システムの洗い出し
システム階層図
用語（ドメイン）一覧
  • 用語の標準化
  • 用語の定義
論理データモデル
  • データ項目
  • データの関連性
システムフロー図
  • データと機能の関係
  • 機能の処理順序
機能仕様書
  • 機能の詳細（Input, Process, Output）
  • 人とシステムの区別
機能/エンティティマトリックス
  • 機能に対する各エンティティのCRUD
エンティティ仕様書
  • データ項目の属性、桁数、制約（NOT NULLとかUNIQUEとか）
非機能要求仕様書
  • 非機能要件の詳細

（うちのチーム的に）必要な外部設計資料とは

ここからがサビ
自分たちが作っているドキュメントと、研修で習ったドキュメントとを繋ぐ。

システム階層図 -> API・バッチ一覧

単純に実装する機能の一覧。
資料として明示的に作らない場合でも、チケット管理ツールのエピック等で表現されてるイメージ。

用語一覧 + 論理データモデル（+ ちょっとコンテキスト図） -> ドメインモデル

ドメイン名は見ればわかる名前、そのものの本質を表す名前をつけるようにしている。そのため、用語の意味はドメイン名によって表現される。
通常ドメイン名はなるべくサービス仕様書に記述されている言葉を用いるので、その場合はサービス仕様書内で意味も定義されているはず。
システム的な都合で作成されたドメインの場合など、業務に現れないドメインの場合は、外部設計仕様書に別途記載する必要がありそう。

データの関連性は、モデル中の多重度、依存関係で表現される。

関連するサブシステムとの結合もドメインモデル中に表現している。
これらを書くことで、開発領域も可視化できる。

システムフロー図 + 機能仕様書 -> ユースケース記述・ロバストネス図

要求の機能をより具体的に落とし込んだドキュメントとして同じ位置だと考えた。 ユースケース記述は、文章でユースケース単位のInput, Process, Outputを表現できる。(≒ 機能仕様書)

ユースケース記述はロバストネス図のインプットになる。図にすることで、

  • 人（アクタ）とシステム（エンティティ・コントローラ）の区別
  • データ（エンティティ）と機能（コントローラ）の関係
  • 処理順序

あたりが自然に表現できそう。
ユースケース記述とロバストネス図だと切り口がユースケースという視点になるけれど、 機能とデータと人、それぞれどう関係しているかを表す分には十分かなと思う。

もうちょいシンプルに機能とデータの関係を表した図をいつも書いていたけど、あれが何図なのかわからない （ずっとコンポ図と呼んでいたけど、ちゃんと調べたらなんか違う気がする…）。

機能・エンティティマトリックス -> 状態遷移表
  • 特定のイベントが起きた場合のエンティティの状態

研修中はこれが似たような位置だと思ったけど、社内で聞いてみたら設計思想によって使い分けた方が良さそうという話になった。

弊社はイベントドリブンで作ってることが多いので状態遷移表をよく書いてるけど、 CRUDは外部のサブシステムの機能から呼ばれた場合とかも書ける。
なにかのイベントが起きたことを検知して自分の状態が変わるのが前者、 このエンティティはこの状態になれ！っていうのが後者の考え方。 たぶん。

ほか、普段あんまり作ってないもの

  • 非機能要求一覧
  • コーディング規約

非機能要件の確認は冒頭に書いた上に、最近はデザインレビューの項目でもあるので、設計の初期段階で明確に検討するべきなのだと感じた。抜けがち。

コーディング規約はうちのチームは放棄…わりと察する系（つらい）。

  • エンティティ仕様書 -> テーブル設計（内部設計）

エンティティ仕様書は桁数とか制約も書くので、うち的にはテーブル設計だと思うんだけど、 このあたりまで外部設計の段階で書くものだとは思ってなかったので意外。
研修中でも物理データモデル設計は内部設計側にあるので合ってるんだけど、たとえばユニーク制約とか貼ったら、このデータはユーザごとに一意なんですとか、 そういうレベルの話は要求者側に認識してもらっても良いのかもな〜と思った。

まとめ：外部設計ではどんなドキュメントが必要なのか？

結論、これを作れば設計はばっちりのはずだ！

さいごに

この研修を受けた目的は、標準を知らない自分が、社外で標準的な開発プロセスを学んできた人と話せるようになることでした。

で、研修で世間の標準を学んでみてよかったことがあって、
「自分の中に標準があることの安心感、自信」
を感じられるようになったこと。

これまで外部設計も見よう見まねでこれがほしいあれがいるかもと付け足したり消したりしながら迷走していた状態だったのですが、
たとえば、これは外部設計で書くべきなんですか （開発チーム内部で共有できていれば十分な内容なのでは？）という問いに対して、前は答えられなかったけれど、研修を受けてからは 「これは自分が勝手に言っているだけのものではない」「要求元に確認したほうが良い内容だ」「こういう内容が必要だ」 という裏付けがある状態になったので、多少自信を持って話せるようになった。

ある程度の現場経験を積んでから理論を学ぶと、ここで言われてることって今までやってきたあれなんだ！ というような気づきを得られるようになり、最近は読書もすごく楽しくなっているのですが、研修もとても良いインプットになりました。めちゃくちゃ忙しくて死ぬかと思ったけど本当に行ってよかった。

あと余談ですが最近ユースケース駆動開発実践ガイドを読んでるのでもろ影響されてる（ロバストネス図のくだりとか）。

以上、ここまでお読みいただきありがとうございました。
この内容に対する見解がありましたらぜひ教えてください。