シリコンバレーでは、「プロジェクトを始める前に何をすべきか?」と尋ねると、10人に9人が「デザインドキュメントを書く」と答えるでしょう。 A エンジニア間で共有されたファイルで、コードが書かれる前に実装される機能を記述する。 デザイン文書はしばしば複数のセクションから構成される: design document (design doc) この例 この例 概要:実装する機能を説明するいくつかの簡単な文。 動機づけ:なぜこの機能を実装しているのか? プレビュー:機能が実装された後、機能はどのように見えますか? テクニカルオプション:この機能を実装するにはどのようなテクニカルオプションが必要ですか?それぞれの利点と欠点は何ですか?どちらを選び、なぜですか? 必要な実装詳細:コードテンプレートのリスト、テスト方法、ログを書く方法など 設計文書は高いレベルでなければならないことに留意することが重要です。 主な著者は設計文書を編集し、同僚は文書にコメントすることによって著者とコミュニケーションをとります。このコミュニケーションプロセスはしばしば数日または数週間続きます。著者と同僚が文書の内容に合意すると、コードベースに統合することができます。 設計文書をプロジェクトに組み込むこのプロセスは、多くの利点を提供します。 あなたのアイデアを簡潔で論理的に明確な言語で表現することができれば、それは機能の実装の深い理解を示します。逆に、あなたが何を書きたいかを表現することもできない場合は、機能を実装することはさらに困難になります。あなたの設計文書にコメントすることによって、あなたの同僚はまた、あなたのアイデアをレビューし、事前に問題を発見し、論理的な欠陥を指摘し、さらにはより良い実装方法を提案するのに役立ちます(私は私の周囲の同僚が常により良いソリューションを提示し、私の思考における論理的なギャップを特定していることを繰り返し発見しました)。 First, design documents help you clarify your thoughts. 彼らは、すべての人の技術的思考を透明にし、コードベースはより維持可能になります。設計文書がすべての人が承認された場合、すべての人がプロジェクト全体の所有権を有し、プロジェクトの高い全体的なエンジニアリング品質につながるコードの品質を改善するのにより意欲的になります。 Second, design documents help the entire team reach a consensus. 新しいチームメンバーや他のチームの同僚は、設計文書を通じてコードベース全体の高レベルの理解を得ることができます。 Third, design documents are an excellent supplement to code. 長い会議に比べて、デザイン文書は、同僚(異なるタイムゾーン)が自分自身の適切な時間に静かに独立して反省し、彼らの考えを改良し、著者にフィードバックを提供することを可能にします。 同僚間のプレデベロッパの議論は、効果的に設計アプローチ全体をレビューし、欠陥のリスクを大幅に減らすことができます(私を信じてください、私は一度以上に怠惰であり、直接コードを書きましたが、開発の日々が役に立たなくなったことを発見しました)。 Fourth, design documents help teams save time. 議論に参加する同僚は、設計文書が解決することを目指す問題に興味を持っている人々です。設計文書を通じて、彼らは迅速に小規模なチームを形成し、十分な情熱を持って作業を効率的に完了することができます。 Fifth, design documents are excellent for organizing teams. デザイン文書はしばしば著者のエンジニアリング能力、問題解決における思考の明確さ、重要な問題を解決する能力を反映します。 Sixth, design documents are excellent material for promotion. デザインドキュメントを書くことはチームに多くの利益をもたらすので、なぜ誰もがこの慣行に従わないのでしょうか? 私の観察から、それは次の誤解のせいかもしれません。 「デザインドキュメントを書くことはあまりにも困難なことですが、もしかしたら最初にコードを始めるだけでしょうか?」 デザインドキュメントを書くのが難しい場合は、著者が問題を十分に理解していないこと、そして彼らの選択した実装方法が間違っている可能性があります。 「もし私がドキュメントを書くのをあきらめていたら、私はすでにコードを完成させただろう」 すべては適度に。 設計文書が必要かどうかは、プロジェクトの長期的なコードの品質と維持可能性に依存します。 機能が実装しやすいし、その論理が単純な場合は、機能を説明するための問題を作成するだけで十分であり、コードのメンテナンスとチームの調整はコードのレビューを通じて達成できます。 「私はこれに優秀で、コードを直接実装して同僚に印象を与えるようにしてください」専門分野を持つことはプラスですが、チーム内でのコミュニケーションも同様に重要です。一方で、同僚が著者のアプローチを理解していない場合、コードレビューを実行するのは困難です。 これらの認識を変え、自分の快適ゾーンから抜け出し、デザイン文書を書き始めて、他人のデザイン文書に積極的にコメントするよう努めます。 ある時、私はある同僚に「他の人のコード、特にPythonのような言語で、書くのは簡単だが読むのは難しい」と文句を言ったが、同僚は「心配しないで、彼らもあなたのコードを理解できない」と答えた。
