Design Docを書くことで、保守性と開発スピードを上げる
今回は、Design Documentを書くことで開発スピードを上げ、コードの保守性を向上させる方法について取り上げます。
記事に対する疑問や感想、意見などXでのポストや記事へのコメントをいただければ、今後のコンテンツの改善に役立てさせていただきます、よろしくおねがいします。
Design Document
日本だと2007年の Google Developer Day Tokyo での鵜飼氏のプレゼン等によって、広まっていった記憶があります。
「Googleのソフトウェアエンジニアリング」には以下のように説明されています。
デザインドキュメントの作成は、新システムのデプロイ前にエンジニアが着手する最初のプロセスである。
優れたデザインドキュメントは、扱う対象に設計のゴールと設計の実装戦略を含み、鍵となる設計上の決定を、ここのトレードオフに重点を置いた形で提案する。
最も優れたデザインドキュメントというものは、設計のゴールを提案し、設計の各種代案を網羅して論じ、それらの代案の強みと弱点を示す。
優れたデザインドキュメントはさらに、一旦承認されると、履歴の記録として働くだけではなく、そのプロジェクトがそのゴールの達成に成功したかを計測する尺度にもなる。
私が、Design Docを書くのに「デザインドックで学ぶデザインドック」を参考にして、Design Docを書いていました。
実用的なDesign Document
新しいシステムやプロダクトを開発する際、システム全体のアーキテクチャ設計にDesign Docを用いると、以下のような利点があります。
脳内が整理され、理解が深まり、考慮漏れが防げる
実装前に設計のレビューが受けられ、FBを得られる
新しいシステムやプロダクトを開発する際のシステム全体のアーキテクチャ設計のようなものに用いられており、普段使いするには結構ヘビーかつtoo muchな部分もあります。
経験的に、機能開発レベルでのプラクティカルなDesign Docのボリュームは以下の通りだと考えています。
ゴール: この設計・実装によって、実現したいこと、解決したい問題を書く
背景: なぜこの実装・設計を行っているかという背景を書く
設計: どういうデザインにするかとその理由を簡潔に書く。コアなロジックや設計を自然言語や図で表現する。
ドキュメントは、書かれたり書かれなかったりする。もしくは形骸化するというのがよくありがちなアンチパターンなので、実用的なレベルで実行されていくほうが、たまに書かれる理想的なドキュメントより、価値が高いです。
ドキュメントの主な役割
私は、ドキュメントは主に2つの役割があります
いまの自分、チームメイトのため
将来のチームメイト（将来の自分も含め）
いまの自分、チームメイトのため
レビューによりフィードバックを受け、認識を揃え、合意を得ることが目的です。脳内を言語化することで、自分の思考を客観視しレビューが可能になります。
将来のチームメイト（将来の自分も含め）
設計背景が記述されていることで、コードだけでは汲み取れない意図が理解しやすくなります。検討事項も記述されていると、車輪の再発明を防ぐのに役立ちます。
会社や事業のフェーズやチームの成熟度に応じて、どの役割が優先されるかが異なるかと思いますが、Design Doc自体の役割を理解し、目的に合った記述を行うことが大切です。
DesignDoc運用の実例
Design Docを書くことで、一人開発でもチーム開発でも保守性と開発スピードを向上させることができます。具体的な事例を紹介します。
開発組織が40名ほどで、1チームが6-8名のフルスタックチームで構成されていました。Design Doc導入前はコードレビューの段階で設計レベルの課題が見つかることが多かったです。しかし、Design Docを導入したことで、以下のようなフローになり、手戻りが大幅に減少しました。
PRD記述
DesignDoc記述
実装
受け入れテスト
QA
リリース
不確実性の低い機能開発の場合
PRDを元に、開発チームの1名もしくは複数名でDesign Docを記述し、チーム内でレビューを行い、設計が承認されたら開発に入るというような形で運用を行い、基本的にはコードレビュー時には細かい指摘のみになるようになりました。
不確実性の高い機能開発の場合
実装前に、Design Docを書くのが難しいというような、新規性や不確実性の高い開発の場合は、2,3名でモブプロをして、サンプルで実装しながら検証進めていきながら、Design Docを書くというようなやり方で進めました。
わからないから書かないというのではなく、わかる部分を広げていき、ファクトを積み上げて、全体像を明らかにしていくという形をとっていましたが、これはとても良いアプローチだったと思います。
コードレビュー時に設計上の懸念があっても、大きな手戻りになるのでレビュワーが指摘しづらいというような心理的な課題があったのですが、Design Docの段階でレビューをいれることで、そういった心理的な障壁が生まれにくくなったことも保守性を向上させる要因でした。
大事なことなので、もう一度いいますが、Design Docを書く開発と書かない開発が発生したりすると、開発プロセスにムラが生まれ、プロダクトの品質にも影響を与え、結果的にスピードの低下と品質の低下を招きます。
自分たちの型にはめることができないケースに直面した場合は、型をアップデートする、型にハマらない差分を埋めに行く、もしくはその両方を行うのが大切です。
Hi-Outcomeに関して
私たち「Hi-Outcome」は、開発チームの規模が10-100名の企業を中心に、開発スピード向上支援を行っています。
開発にお悩みの方がいましたら、是非お気軽にお問い合わせください。
【Hi-Outcomeコンサルティング】
【Hi-Outcome開発診断】