MyEnigma

とあるエンジニアのブログです。#Robotics #Programing #C++ #Python #MATLAB #Vim #Mathematics #Book #Movie #Traveling #Mac #iPhone

Googleなどで利用されているDesign Doc入門


How Google Works (日本経済新聞出版)

目次

はじめに

GoogleなどのIT企業がソフトウェアを開発する際には

Design Docというドキュメントを利用しているそうです。

 

Design Docは「設計書」と訳されることが多いですが、

日本語の設計書とは少し意味合いが違うようです。

 

今回は、このDesing Docの要点を、

末尾の参考資料を元に勉強してみたので、

自分用のメモとしてまとめておきたいと思います。

Design Docの要点メモ

Design Docは、

これから新しく開発しようとするソフトウェアの全体の設計や、

既存のコードのpatchやプルリクエスト(PR)のコード変更の

基本的な要点をまとめる文書です。

  

PRを作成する前に、Design Docを作成して、

コード変更をドキュメントベースで議論することで、

レビュアーに変更の背景や、

なぜ様々な選択肢の中で、この方針で変更をするのかを

理解しやすくしてもらうメリットがあります。

 

Design Docには、下記のような項目を記入することが多いようです。

  • 背景、目的 (Why?)

  • 検討した別の方法 (alternatives considered)

  • トレードオフ (Why not?: なぜ別の方法にしなかったのか?)

  • 設計、アーキテクチャ (How?)

  • メンバー (担当者やレビュワー) (Who?)

  • セキュリティやプライバシーについての考察など

  • 他プロジェクトとの関連性

  • テスト,モニタプランなど

基本的には、ソースコードを見てもわからない部分を

Design Docに書いて、議論するのが一般的のようです。

  

このDesign Docはプロジェクト立ち上げ時に

1~2週間をかけて書き、Design Docのレビューを受けながら、

ある程度、大筋の議論が収束したら、PRの作成を始めます。

PRのレビュー中にも、そもそものDesignが変わることも多いので、

そのときには、Design Docもコードと一緒に直していくようです。

 

人によっては、

プロトタイピングしながら Design Doc を書く人もいるようです。

Design Doc が書き上がる頃には大体動くものができていて、

議論を通してこのプロトタイプを叩き上げて完成形にします。

  

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

十分に詳細でありながら、忙しい人にも読んでもらえるように

ある程度短くする必要があります。

大規模なプロジェクトでも、10〜20ページ程度が限度とのことです。

 

逆に、ある程度大規模なプロジェクトやコード変更では

Design Docは必要ですが、

1-3 PR程度で完結する作業であれば、

コードの変更や commit descriptionで背景がわかるので、

Design Doc は不要な場合が多いそうです。

 

Design Docを書くメリットとしては、下記があります。

  1. 解決したい問題が浮き彫りになり、解くべき問題に取り組んでいるのかわかる

  2. チームで問題や課題を共有でき、方向性を共有できる

  3. 各々が好き勝手に実作業に取り掛かり、齟齬が出る可能性を防ぐことができる。

  4. 文書に落とし込むことにより設計や実装を 具体的にイメージできるようになる

  5. フォーマットが統一されているため、見落としがちなポイントを設計時点で検討できる。

  6. コードには現れない、Why not (なぜ別の方法をしなかったのか?)を議論できる

  7. 実は他の人が以前、同じようなコードを作成していたことを知ることができる。

 

参考資料

www.atmarkit.co.jp

snowlong.hatenablog.com

please-sleep.cou929.nu

xtech.nikkei.com

shimo5.me

blog.livedoor.jp

github.com

nhiroki.jp

kenmaz.hatenadiary.jp

docs.google.com

kenmaz.hatenadiary.jp

messagepassing.github.io

www.industrialempathy.com

blog.riywo.com


How Google Works (日本経済新聞出版)

 

MyEnigma Supporters

もしこの記事が参考になり、

ブログをサポートしたいと思われた方は、

こちらからよろしくお願いします。

myenigma.hatenablog.com