デザインドキュメントについて

こんにちは、 @kz_morita です。

先日行われた勉強会でデザインドキュメントというソフトウェア開発時に各ドキュメントについて聞いて，興味が湧いたのでしらべてみました．

デザインドキュメントとは

デザインドキュメントは Google などの企業でソフトウェア開発を行う際に一緒に書かれるドキュメントのことです．

ソフトウェアがどのような問題をどのように解決するのかを，ソフトウェアよりより高いレベルで伝えるための手段としてもちいられます．

何を書くべきか

このドキュメントには，実装のアプローチや，主要な設計上の決定事項，考慮されたトレードオフなどが書かれます．

何を書くべきかという明確なルールはないためそれぞれのプロジェクトに合った形で改造していくのが良さそうです．

以下に自分が参考にした一例を載せます．

- プロダクト開発・機能開発・改善の背景
    - 課題は何か＝何を解決するのか
- システムの技術的概要, アーキテクチャー図
    - スコープ
- プロジェクトの参加者
- 用語集
- 選定した解決手段について
    - 選定の根拠、トレードオフ
    - 詳細なアーキテクチャー図など
    - PoCの内容と結果
- 選定しなかった解決手段について
    - 手段の概要と、不採用の根拠
- 外部依存の概要
- 機能そのもの、解決手段についてセキュリティ観点からの考察
- 現時点で考えられるリスク
    - リスクの概要
    - 考えられるリスクへの対応策
    - 現時点で対応策を取らない理由
- テスト観点からの考察
- 運用観点からの考察
    - 運用時の考慮事項
    - 障害の発見と復旧手法
- References
- etc...etc..

特に重要なのは，考慮したけど採用しなかったものや，技術選定の際の選定基準やトレードオフ，またその技術を使うことで起こりうるリスクなどになるかなと思います．

デザインドキュメントの価値

メリット

ドキュメント化することにより，早い段階で設計のレビューを行ったり問題点を話し合うことで手戻りがすくなるほか，組織内での合意形成などにも役に立ちます．

そして何より，考古学をしなくてよくなるということが最大のメリットに感じました．

ここで考古学といったのは，例えば古いシステムの古い仕様について聞きたいときに，プロジェクトに当時在籍していた人がすでに退職してわからなかったりする場合には，コードやコミットログ，チャットのログなどから状況を推測する必要がある事象のことです．

ドキュメントの形になることにより，なぜこういった仕様なのか，なぜあの技術を採用しなかったのか，作られた当初に考えられたリスクは何なのか，などがソースコードから読み解かなくても良くなります．

特になぜ，おこなわなかったのかという判断については，ソースコードから読み解くのが非常に難しいためこれらの情報が残っていることはとても重要に感じます．

結果として古いコードに対しても修正を行いやすくなり，継続的に改善がしやすくなる期待があります．

デメリット

純粋にドキュメントの作成はオーバーヘッドになります．そのため，その労力がこの文書によって得られるメリット（設計に関する，共有やレビュー，合意形成など）より大きいかといった点には注意する必要がありそうです．

たとえば，解くべき課題がとてもシンプルで誰にとっても明確な場合，このデザインドキュメントの価値は低くなるでしょう．

書くべきか

個人の意見としては，デザインドキュメントはこれから積極的に書いていきたいと考えています．理由としては，もちろんドキュメントという形で残すことによるメリットもありますが，加えてデザインドキュメントを書くという工程に，PoC やプロトタイピングが含まれることにあります．

何らかの技術を選定することはなんらかの技術を捨てることであり，なにをどういう基準で捨てるか（トレードオフをしっかり理解した上で）ということは重要だと思っています．

自分はつい目の前の技術で解決しようとしてしまうことがあるため，デザインドキュメントを書くという行為を通して，他のよりよい選択肢はないか？ないとしても他にどういった候補があり，どういう理由で採用しないのかをしっかり検討する良い機会になると考えます．

運用

ドキュメントでしばし問題になるのがそのメンテナンスコストだと思います．メンテナンスされてないドキュメントがあるくらいならば，ドキュメントが無い方が誤解がなくましという意見もあると思います．

運用としては，ソースコードとデザインドキュメントは同じようなサイクルで更新していくのが良さそうです．デザインドキュメントをつくり，実装をはじめていくうちに設計の問題点が浮き彫りになることは一定数起きると思います．そういったときに，ソースコードをすぐに修正したい気持ちを抑えて，ドキュメントを直していくということが重要だと考えます．ドキュメントの更新のイテレーションをできるだけ短く保つと一回あたりの修正量も減りそうです．

ただ，この方法は純粋にソースコードだけを修正するよりも手間がかかるのは事実なのでプロジェクトの状態などによってやるべきかどうかは判断が必要そうです．

まとめ

今回はデザインドキュメントについて軽くまとめました．いわゆる設計書なのですが，どういった観点で情報を残すべきなのかといった点を知ることができて良かったです．

また，個人的に未知の技術に対して取り組むときに，実装段階になってから設計や仕様のまずさに気づくという経験が何度もありました．このデザインドキュメントを意識的に書くことですこしでもそういった事象が減るかもしれないため，まずは積極的に書いていくようにしていきたいと思います．

デザインドキュメントに関する資料

デザインドキュメント例

公開されている実際のデザインドキュメントがあったので載せておきます．

普段からソフトウェアの設計やアーキテクチャに関心があり色々調べていたのですが、最近発売された、「Clean Architecture」がとても良さそうなので読みました。結果すごく良かったのでエッセンスをまとめます。書籍「Clean Architecture」 Clean Architecture 達人に学ぶソフトウェア構造と設計この本は、「ソフトウェアの価値とはなんなのか」という着眼点から始まり、プログラミングのパラダイムに軽く触れたのちに、アーキテクチャの話に深く入っていきます。題名から、いわゆる設計手法としての「Clean Architecture」についての話かと思いがちですが内容はアーキテクチャとは何か、どういった目的意識があるのかいうアーキテクチャ全体的な概念などの非常にためになる話が多くいくつも気づきがありました。以下、簡単にまとめます。ソフトウェアの価値とはソフトウェアの価値は、「提供する機能」と「更新できること」にあります。「提供する機能」とはそのままの意味で、そのソフトウェアが問題を解決することに価値があるということです。「更新できること」は需要や周りの環境の変化に応じてソフトウェアが変化できること自体に価値があるということです。ソフトウェアの「ソフト」とは柔軟に変化できることを表していて、継続的に更新できることは大きな価値になり得ます。アーキテクチャとオブジェクト指向アーキテクチャの目的とは、ソフトウェア継続的に更新し続けられる柔軟な状態にすることにあると言えるでしょう。このため、変更が頻繁に起きるところと少ない箇所を分離しお互いが影響しないように適切にソフトウェアの境界を引いて行くことが重要です。またソフトウェアには「方針」と「詳細」があるという風に言われています。方針はソフトウェアがどのように問題を解決するかの方針、つまりはビジネスロジックのことを指します。詳細とはデータベースや、フレームワーク、UIなどのことを指します。この二つのうち、変更が頻繁に起こるのは「詳細」の方だと思います。ソフトウェアの目的は「方針」側にあります。 (データベースの種類や、どのフレームワークを使用するかなどの詳細はソフトウェアの本質ではないということ) この「方針」が「詳細」の変更に影響されないように（詳細に依存しないように）依存関係を管理することがアーキテクトの腕の見せ所です。依存関係を完全に管理するためには、オブジェクト指向プログラミング (以下OOP) のパラダイムが非常に役に立ちます。 OOPの特徴であるポリモーフィズムにより、オブジェクト (あるいはコンポーネント) 同士の依存の方向を制御することができます。具体的には、SOLIDの原則のDIP (依存関係逆転の法則) で依存の方向を逆転させることで、方針が詳細に依存しないようにして行くことができます。ちなみに、SOLIDの原則については以下の本に非常に詳しく書かれています。アジャイルソフトウェア開発の奥義第2版オブジェクト指向開発の神髄と匠の技私もこの本に出会うまでは、SOLIDの原則について全く知りませんでした。非常に分厚く読み応えがすごいですが、今ではプログラミングをする上の指針となる大事な原則を得られ、読んで良かったと思える一冊です。話を戻しまして、書籍「Clean Architecture」には、ソフトウェアのどこに境界を引くのか、依存関係をどうやって管理するのか、についての具体的なエッセンスが多く書かれていました。ここでは詳細には触れませんが、どのようにコンポーネントを分離するのかや、設計手法であるクリーンアーキテクチャの紹介などが印象的でした。アーキテクチャの概念等の抽象的な話題から、実際にどうアーキテクチャを考えて行くかの指標になる具体的な話題まで揃っていて非常にお得感のある本でした。感想最初にこの本を読もうと思ったのが、kindle版の無料サンプルで公開されている以下の文を読んでこれは面白そうだぞっと感じたのがきっかけです。崩壊したコードを書くほうがクリーンなコードを書くよりも常に遅いＲｏｂｅｒｔＣ．Ｍａｒｔｉｎ; 角征典; 高木正弘. Clean Architecture 達人に学ぶソフトウェアの構造と設計 (アスキードワンゴ) (Kindle の位置No.460). 株式会社ドワンゴ. Kindle 版. 他には、