17 November 2009

Google の Design Doc について

GoogleのDesign Docについて調べました.Design Docとは,Googleのエンジニアがソフトウエアを開発する際に必ず書くドキュメントです.

一般的にDesign Documentというと,設計仕様書のことをさすようです.設計仕様書はソフトウエアのシステム的な設計がどのように行われているかを記したドキュメントです.一方でGoogleのDesign Docは,あるソフトウエアについて,何を・なぜ・どのように作るかを記したもののようです.両者ともあつかっている対象や,対象としている読者が少しずつ異なっています.このエントリーではGoogleのDesign Docについて扱います.

Design Docの内容

Design Docについては,Googleの鵜飼文敏さんによる以下のプレゼンテーションで触れられています.

鵜飼文敏さんの講演「ハッカーのソフトウェアエンジニアリング」の動画を公開しました:ITpro

YouTube - Google Developer Day Tokyo - 鵜飼 文敏

へ~たのめも:Google のソフトウェア・エンジニアリング - livedoor Blog(ブログ)

Design Docだけでなく,Googleでのソフトウエアの開発方法について語られているので,興味深いプレゼンテーションです.

上記のプレゼンテーションによると,Design Docは以下のような内容のドキュメントです.

  • 背景、目的(Why?)
  • 設計(How?)
  • メンバー(Who?)
  • セキュリティやプライバシーについての考察など
  • テスト,モニタプランなど

実例

WebKitの開発に参加しているGoogleのエンジニアがWebKitのMLにポストしたものなど,Web上でいくつかDesign Docの実例がみられました.

WebKit WebSocket design doc - Google ドキュメント

Googleのdesign docを眺めてみる - kenmazのはてな

WebKitのWeb Socketという機能についてのDesign Doc.上記の鵜飼さんをはじめ,Google Japanの方々によるもののようです.

Ruby Simplified - Google ドキュメント

WebKitのRuby(言語ではないほう)機能についてのDesign Doc.Roland Stainer氏によるもの

no title

WebKitのSharedWorkerという機能についてのDesgin Doc.Drew Wilson氏によるもの.

Sought (htdig) archive file not found

こちらはWHATWGのMLへポストされていた,John Gregg氏によるDesign Doc.

Extensions - The Chromium Projects

こちらはGoogleのDesign Docとは違うもののようですが,Chromiumのエクステンションに関するDesign Docとよばれるドキュメントがありました.

ドキュメントについて

最近,自分/他人があまり未来のことを考えずに書いたコードをメンテナンスして,非常に苦しめられたことが何度かありました.そのため,コードのメンテナンス性・再利用性を高めるにはどうしたらいいかということを最近よく考えています.

メンテナンス性・再利用性向上のための一つの方法として,ドキュメンテーションがあると思います.ドキュメントを書く事で,あとからコードを読む際の理解の手助けになり,またコードを書く前に作りたい物をきちんと文章化する事によって,問題を整理し目標を明確化できるという副次的な利点も期待できます.

そのために,まず何をドキュメントに書けばいいのか,先人の知恵を借りようと言う事で,googleのDesign Docについて調べたりしました.その結果わかった事は,ドキュメントの内容は

  • ドキュメントの目的
  • 対象としている読者(開発者か,ユーザか,あるいは自分など)
  • プロジェクトのコードの量

に応じてかわってくるという事です.

今回の場合は,自分一人でやっているプロジェクトで,のちのち自分が困らない事を目的としています.そのため対象読者は将来の自分で,コードの量は少なめです.よって,あんまり詳細なことを書いても仕方ないので,必要最低限のないようにしぼったものが良いと思います.というわけで,現在は次のような内容を書けばいいんじゃないかと考えています.

  • プロジェクトの目的・背景
  • おおまかな設計
  • 依存しているライブラリとバージョン
  • 考察事項,todo,今後の課題など