ベイズの公式

ベイズの公式

2014年9月2日火曜日

プログラマの意思表明 "Design Doc"を書こう!

ちょっと時間が経ってしまったが、先日のMIJSシリコンバレー報告会にて耳にした話を紹介したい。

 この報告会によれば、シリコンバレーのソフトウェア系スタートアップ企業では、"Design Doc"が常識として普及しているそうだ。その詳しい内容を聞いてみると、非常によい『温度感』のドキュメントの使い方であり、理にかなっていると感じた。


Design Doc とは?

 プログラマが、これから開発しようとするソフトウェアの設計の要点を文書化したものが Design Docである。いわばプログラマとしての意思表明であり、設計イメージをまとめたラフスケッチでもある。
 ソフトウェアを開発しようとするとき、プログラマの頭の中には骨格となる設計イメージがあるはずだ。大まなかデータ構造や、主要なアルゴリズム、フレームワークの適用方法やツールの種類など「こうすればできるはず」という勝算があるからコードを書き始められるのである。それを文章として書き留めたものがDesign Doc であると言える。


内容は?

 開発しようとする対象物について、背景・目的(Why),  アーキテクチャ・メカニズム方針(How), 参加メンバー(Who) を中心に、プログラマが必要と判断した項目を、要点だけシンプルに述べるものとされる。
 ただし、図やチャートだけのものは原則許されず、日本語(英語)などの自然言語の文章を中心として『読んで分かる(Narrative)』ものであることが原則である。


想定読者は?

 Design Doc を読むのは、同じ開発プロジェクト内の他のプログラマ(将来の自分も含む)や、レビューアーである。
 いわゆる納品ドキュメントにすることは前提としていない。

運用フローは?

 実装に入る前に書き、リポジトリにコミットするなどしてチーム内で共有する。
コードレビューの時に必須の資料とされ、Design Docが無ければレビューを受けられない。
レビューアーは、まず最初にDesign Docを読み、概要を理解してからコードレビューを行うのである。


いわゆる従来の「設計書」と何が違うのか?

 Design Doc は従来の『設計書』とは違うニュアンスを持っている。設計書は、対象について『全てを書き尽くす』ことを前提としていて、要件をできるだけ漏れ無く書き尽くそうとするものであるのに対し、Design doc はソースコードと併用ことが前提で、設計の要点だけをシンプルにまとめれば良いとされている。
 Desgin Docにはソースコードからは読み取りにくい背景やコンセプトを記し、逆にソースコードを見たほうが早い詳細情報はあえて書かないのである。


Design Doc の書き方

 フォーマットにはあまりこだわらない。Markdown や Google Doc など、共有がしやすくてプレーンなフォーマットが好まれるようだ。更新履歴や差分が見やすいものが好ましい。
 見出しや箇条書きを上手く使って要領よくまとめるようにする。


Design Doc のサンプル

 こちのブログ記事に Google の Web Socket 開発時の Design Doc についての良い解説があるので、
参照いただきたい。(なお、この例は Design Doc としては、かなり大作の部類であると思う。もっとコンパクトなものを紹介したかったが、調度良いサンプルを見つけられなかったのである。)


Design Doc をおすすめする理由

 そもそも、ソフトウェア開発におけるドキュメントの取り扱いは、昔から大きな問題の一つである。上流工程重視で、ドキュメントに非常に重点を置く人達や、『ソースコードこそが最良かつ唯一のドキュメントであって、その他はゴミだ』というような急進派の人達まで、喧々諤々の議論が繰り広げられてきた。そこでの問題点は、途中から議論が宗教論争のようになってしまうことだ。エンジニアとしての倫理観・道徳観みたいなもの(『とにかく、ドキュメントは書くべきだ!』とか)と結びつけて語ってしまう人がいて、議論が平行線のまま終わることも多い。

 しかし、ちょっと待て。やはりソフトウェア工学は実践的科学であって、実務的な効用を無視して判断するのはおかしい。そのソフトウェアが使われる分野だとか、期待される信頼性などによってもドキュメントの「重み」は異なってくるはずだ。両極端に走らず、目的にかなったちょうど良い感じのドキュメントの運用ができないものだろうか?
 "Design Doc"は、この疑問に対する答えの一つになりそうな気がするのだが、どうだろう?

 ソースコードに含まれる情報とはできるだけ重複せず、ソースだけを見ても分かりにくい設計の背景や意図を中心に書くという主旨は、合理的でプログラマにも納得しやすいものであると思う。是非みなさんも試して欲しい。

(注1:この話は、Web系やスマートフォンアプリなどの分野での話に限っている。組込み系や、ミッションクリティカルな分野では、古典的な厳密なドキュメント駆動が今後も必要だと思う。ただ、基本設計メモとしては Design Doc が使えるかも知れない。)

(注2:ここいうプログラマとは、「コーダー」の意味ではなく、ソフトウェアを設計し実装する人の意味である。) 

1 件のコメント:

  1. この記事を引用してくださっている記事を発見したので、リンクを貼っておきます。

    http://enk.hatenablog.com/entry/2014/12/07/011033

    返信削除