元記事: https://www.industrialempathy.com/posts/design-docs-at-google/
Googleのソフトウェアエンジニアリング文化の重要な要素の1つは、設計ドキュメントを通じてソフトウェア設計を定義することです。 これらは、コーディングプロジェクトに着手する前に、ソフトウェアシステムまたはアプリケーションの主要な作成者または複数の作成者が作成する比較的非公式なドキュメントです。 設計ドキュメントには、高レベルの実装戦略と主要な設計決定が、それらの決定中に考慮されたトレードオフに重点を置いて文書化されています。
ソフトウェアエンジニアとしての私たちの仕事は、コード自体を作成することではなく、問題を解決することです。 設計ドキュメントの形式のような非構造化テキストは、プロジェクトライフサイクルの早い段階で問題を解決するための優れたツールである可能性があります。これは、コードよりも簡潔で理解しやすく、問題と解決策をより高いレベルで伝達するためです。
ソフトウェア設計の元のドキュメントに加えて、設計ドキュメントはソフトウェア開発ライフサイクルで次の機能を果たします。
- 変更を加える際の設計上の問題を早期に特定することは、依然として安価です。
- 組織内の設計に関するコンセンサスを達成する。
- 横断的関心事の考慮を確実にします。
- 上級エンジニアの知識を組織に拡大します。
- 設計上の決定に関する組織の記憶の基礎を形成します。
- ソフトウェア設計者の技術ポートフォリオの要約アーティファクトとして機能します。
デザインドキュメントは非公式のドキュメントであるため、コンテンツの厳密なガイドラインに従っていません。ルール1は次のとおりです。特定のプロジェクトに最も適した形式でそれらを記述します。
そうは言っても、ある構造は本当に有用なものとしての地位を確立しています。
このセクションでは、新しいシステムが構築されている状況と実際に構築されているものの概要を読者に示します。これは要件ドキュメントではありません。簡潔にしてください！目標は、読者をスピードアップさせることですが、いくつかの以前の知識を想定し、詳細情報をリンクすることができます。このセクションでは、客観的な背景の事実に完全に焦点を当てる必要があります。
システムの目標が何であるか、そして時にはもっと重要なことに、非目標が何であるかについての箇条書きの短いリスト。非目標は、「システムがクラッシュしてはならない」などの否定された目標ではなく、合理的に目標になる可能性があるものの、目標ではないように明示的に選択されていることに注意してください。良い例は「ACIDコンプライアンス」です。データベースを設計するときは、それが目標であるか非目標であるかを確実に知りたいと思うでしょう。また、それが目標ではない場合でも、目標の達成を妨げるトレードオフが導入されていない場合は、それを提供するソリューションを選択する可能性があります。
このセクションでは、概要から始めて、詳細を説明します。
フクロウの描き方の可視化。最初の写真：「1。いくつかの円を描く」というラベルの付いた2つの円。 2番目の写真：「2。残りのフクロウを描く」というラベルの付いた自分の写真
設計ドキュメントは、ソフトウェアの設計で行ったトレードオフを書き留める場所です。これらのトレードオフに焦点を合わせて、長期的な価値のある有用なドキュメントを作成してください。つまり、コンテキスト（事実）、目標、および非目標（要件）が与えられた場合、設計ドキュメントは、ソリューションを提案し、特定のソリューションがそれらの目標を最もよく満たす理由を示す場所です。
より正式な媒体で文書を書くことのポイントは、目前の問題を適切な方法で表現する柔軟性を提供することです。このため、実際に設計を説明する方法についての明確なガイダンスはありません。
そうは言っても、設計ドキュメントの大部分にとって意味のあるいくつかのベストプラクティスと繰り返しのトピックが浮上しています。
多くのドキュメントでは、system-context-diagramが非常に役立ちます。このような図は、システムをより大きな技術的展望の一部として示しており、読者がすでに慣れ親しんでいる環境を考慮して、新しい設計をコンテキスト化することを可能にします。
さまざまなシステムが互いにどのように関連しているかを示すブロック図。実際のテキストは単なる例であり、例を理解するために見る必要はありません。 システムコンテキスト図の例。
設計中のシステムがAPIを公開している場合は、通常、そのAPIをスケッチすることをお勧めします。ただし、ほとんどの場合、正式なインターフェイスまたはデータ定義をコピーしてドキュメントに貼り付けようとする誘惑に耐える必要があります。これらは冗長で、不要な詳細が含まれ、すぐに古くなるためです。代わりに、設計とそのトレードオフに関連する部分に焦点を合わせます。
データを保存するシステムは、これがどのように、どのような大まかな形で発生するかについて話し合う必要があります。 APIに関するアドバイスと同様に、同じ理由で、完全なスキーマ定義をコピーして貼り付けることは避けてください。代わりに、設計とそのトレードオフに関連する部分に焦点を合わせます。
新しいアルゴリズムが説明されている状況を除いて、設計ドキュメントにコードや擬似コードが含まれることはめったにありません。必要に応じて、設計の実装可能性を示すプロトタイプにリンクします。
ソフトウェア設計の形状、したがって設計ドキュメントに影響を与える主な要因の1つは、ソリューション空間の制約の程度です。
極端な例の1つは、「グリーンフィールドソフトウェアプロジェクト」です。ここでは、私たちが知っているのは目標だけであり、解決策は最も理にかなったものであれば何でもかまいません。このようなドキュメントは多岐にわたる可能性がありますが、管理可能なソリューションのセットにズームインできるようにする一連のルールをすばやく定義する必要もあります。
一方、可能な解決策が非常に明確に定義されているシステムですが、目標を達成するためにそれらをどのように組み合わせることができるかはまったく明らかではありません。これは、変更が難しく、希望どおりに動作するように設計されていないレガシーシステム、またはホストプログラミング言語の制約内で動作する必要のあるライブラリ設計である可能性があります。
この状況では、比較的簡単にできることをすべて列挙できるかもしれませんが、目標を達成するには、それらを創造的に組み合わせる必要があります。複数の解決策があるかもしれませんが、どれも本当に素晴らしいものではありません。したがって、そのようなドキュメントでは、特定されたすべてのトレードオフを考慮して、最良の方法を選択することに焦点を当てる必要があります。
このセクションでは、同様の結果を合理的に達成したであろう代替設計をリストします。それぞれの設計が行うトレードオフと、それらのトレードオフがドキュメントの主要トピックである設計を選択する決定にどのようにつながったかに焦点を当てる必要があります。
最終的に選択されなかったソリューションについて簡潔にすることは問題ありませんが、このセクションは、選択されたソリューションがプロジェクトの目標を考慮して最適である理由と、読者が他のソリューションをどのように考えるかを明確に示しているため、最も重要なセクションの1つです。不思議に思うかもしれませんが、目標を考えるとあまり望ましくないトレードオフを導入してください。
これは、セキュリティ、プライバシー、可観測性などの特定の横断的関心事が常に考慮されるようにすることができる場所です。これらは多くの場合、設計が懸念事項にどのように影響し、懸念事項にどのように対処するかを説明する比較的短いセクションです。チームは、これらの懸念が自分たちの場合に何であるかを標準化する必要があります。
その重要性から、Googleプロジェクトには専用のプライバシー設計ドキュメントが必要であり、プライバシーとセキュリティに関する専用のレビューがあります。レビューはプロジェクトの開始時までに完了する必要がありますが、設計でゼロから考慮されるように、できるだけ早くプライバシーおよびセキュリティチームと連携することをお勧めします。もちろん、これらのトピック専用のドキュメントの場合、中央の設計ドキュメントでは、詳細に立ち入る代わりにそれらを参照できます。
設計ドキュメントは十分に詳細である必要がありますが、忙しい人が実際に読むことができるように十分に短くする必要があります。大規模なプロジェクトのスイートスポットは、約10〜20ページのようです。それをはるかに超える場合は、問題をより管理しやすいサブ問題に分割することが理にかなっている可能性があります。また、1〜3ページの「ミニデザインドキュメント」を作成することは絶対に可能であることに注意してください。これは、アジャイルプロジェクトの段階的な改善やサブタスクに特に役立ちます。長いドキュメントの場合と同じ手順をすべて実行し、物事をより簡潔に保ち、限られた問題セットに集中します。
設計ドキュメントの作成はオーバーヘッドです。設計ドキュメントを作成するかどうかの決定は、設計、ドキュメント、上級レビューなどに関する組織のコンセンサスの利点がドキュメント作成の余分な作業を上回るかどうかを決定するという主要なトレードオフに帰着します。その決定の中心は、問題の複雑さまたはソリューションの複雑さ、あるいはその両方のために、設計問題のソリューションがあいまいであるかどうかにあります。そうでない場合は、ドキュメントを作成するプロセスを実行する価値はほとんどありません。
ドキュメントが必要ないかもしれないという明確な指標は、実際には実装マニュアルである設計ドキュメントです。トレードオフや代替案を検討したり、意思決定を説明したりせずに、ドキュメントが基本的に「これを実装する方法です」と言っている場合（または、ソリューションが明白でトレードオフがないことを意味する場合）、実際のプログラムをすぐに作成する方がよいでしょう。
最後に、設計ドキュメントの作成とレビューのオーバーヘッドは、プロトタイピングと迅速な反復と互換性がない場合があります。ただし、ほとんどのソフトウェアプロジェクトには、実際に既知の一連の問題があります。アジャイル手法にサブスクライブすることは、実際に既知の問題の解決策を正しく得るために時間をかけないことの言い訳にはなりません。さらに、プロトタイピング自体が設計ドキュメントの作成の一部である可能性があります。 「試してみて、うまくいく」というのは、デザインを選ぶ上での最良の議論の1つです。
設計ドキュメントのライフサイクルの手順は次のとおりです。
- 作成と迅速な反復
- レビュー（複数回行われる場合があります）
- 実装と反復
- メンテナンスと学習
あなたはドキュメントを書きます。時には共著者のセットと一緒に。
このフェーズは急速な反復の時間に急速に進化し、問題領域について最も知識のある同僚（多くの場合同じチームに属する）とドキュメントが共有され、明確な質問と提案を通じて、ドキュメントが最初の比較的安定したバージョンになります。 。
ドキュメント作成にバージョン管理ツールやコードレビューツールを好むエンジニアやチームも確かにいますが、Googleの設計ドキュメントの大部分はGoogleドキュメントで作成されており、そのコラボレーション機能を多用しています。
レビューフェーズでは、設計ドキュメントは、元の作成者や緊密な協力者よりも幅広い対象者と共有されます。レビューは多くの価値をもたらす可能性がありますが、オーバーヘッドの危険な罠でもあるため、賢明に扱ってください。
レビューにはさまざまな形があります。より軽量なバージョンでは、ドキュメントを（より幅広い）チームリストに送信して、人々に見てもらう機会を与えるだけです。その後、ディスカッションは主にドキュメントのコメントスレッドで行われます。レビューの重い側面は、正式な設計レビュー会議です。この会議では、作成者がドキュメントを（多くの場合、専用のプレゼンテーションを介して）非常に上級のエンジニアリング対象者に提示します。 Googleの多くのチームは、エンジニアがレビューにサインアップできるこの目的のために定期的な会議を予定しています。当然、そのような会議が行われるのを待つと、開発プロセスが大幅に遅くなる可能性があります。エンジニアは、最も重要なフィードバックを直接求め、より広範なレビューの進捗を妨げないようにすることで、これを軽減できます。
Googleが小さな会社だったときは、デザインを1つの中央のメーリングリストに送信するのが通例でした。これはあなたの会社のために物事を処理するための素晴らしい方法かもしれません。 1つの利点は、会社全体で比較的均一なソフトウェア設計文化を確立したことです。しかし、会社がはるかに大規模なエンジニアリングチームに拡大するにつれて、一元化されたアプローチを維持することが不可能になりました。
このようなレビューが追加する主な価値は、組織の経験を組み合わせて設計に組み込む機会を形成することです。最も一貫して、設計が可観測性、セキュリティ、プライバシーなどの横断的関心事を考慮に入れることを保証することは、レビュー段階で保証できるものです。レビューの主な価値は、問題自体が発見されることではなく、変更を加えるのがまだ比較的安価である開発ライフサイクルの比較的早い段階で発生することです。
状況が十分に進んで、さらなるレビューで設計に大きな変更が必要になる可能性が低いと確信できるようになったら、実装を開始します。計画が現実と衝突するにつれて、欠点、対処されていない要件、または知識に基づいた推測が間違った表面であることが判明し、設計を変更する必要があることは避けられません。この場合、設計ドキュメントを更新することを強くお勧めします。経験則として：設計されたシステムがまだ出荷されていない場合は、必ずドキュメントを更新してください。実際には、私たち人間はドキュメントの更新が苦手であり、他の実際的な理由から、変更は新しいドキュメントに分離されることがよくあります。これは、1つの一貫した文書ではなく、多数の修正を伴う米国憲法により類似した最終的な状態につながります。元のドキュメントからのそのような修正へのリンクは、設計ドキュメントの考古学を通じてターゲットシステムを理解しようとしている貧しい将来のメンテナンスプログラマーにとって非常に役立つ可能性があります。
Googleのエンジニアが、これまで最初の質問に触れたことのないシステムに直面した場合、「設計ドキュメントはどこにありますか？」という質問がよくあります。すべてのドキュメントと同様に、設計ドキュメントは時間の経過とともに現実と同期しなくなる傾向がありますが、システムの作成を導いた考え方について学ぶための最もアクセスしやすいエントリポイントを提示することがよくあります。
著者として、あなた自身に賛成して、1年か2年後にあなた自身のデザインドキュメントを読み直してください。何が正しかったですか？何が間違っていたのですか？今日、違う決断をするためにあなたは何をしますか？これらの質問に答えることは、エンジニアとして進歩し、時間の経過とともにソフトウェア設計スキルを向上させるための優れた方法です。
設計ドキュメントは、ソフトウェアプロジェクトで最も困難な問題を解決することについて明確にし、コンセンサスを得るのに最適な方法です。プロジェクトの目標を達成できず、事前調査を使用して回避できた可能性のあるうさぎの穴のコーディングを回避できるため、コストを節約できます。作成とレビューには時間がかかるため、費用がかかります。だから、あなたのプロジェクトのために賢明に選んでください！
設計ドキュメントの作成を検討するときは、次の点について考えてください。
適切なソフトウェア設計について確信が持てませんか。確実性を得るために事前に時間を費やすことは理にかなっていますか。
関連して、すべてのコード変更をレビューできない可能性のある上級エンジニアを設計に含めることは役立ちますか？
ソフトウェアの設計はあいまいであるか、それについて組織的なコンセンサスを達成することが価値があるように論争さえありますか？
私のチームは、プライバシー、セキュリティ、ロギング、またはその他の横断的関心事を設計で考慮することを忘れることがありますか？
組織内のレガシーシステムの設計に関する高レベルの洞察を提供するドキュメントに対する強いニーズはありますか？
これらの質問の3つ以上に「はい」と答えた場合、設計ドキュメントはおそらく次のソフトウェアプロジェクトを開始するための優れた方法です。