開発プロセスでドキュメントが必要なのはなぜでしょうか? というこの記述についてはどうでしょうか? コード自体が文書化されている 最も一般的なシナリオを考えてみましょう。システムのコード (プログラム、プロジェクト、または製品) は長期間にわたって作成されており、このプロセス中にチームが徐々に変更され、開発者が退職するとシステムに関する特定の知識がチームに持ち去られます。 このような場合、どうすればいいでしょうか? 最も簡単な答えは、システムが元の要件を満たしていることを確認するために、実装の詳細をすべて取り込んだ ことです。 仕様を作成する しかし、このようなドキュメントを事前に作成するのは非常に難しく、開発プロセス中に実装の詳細が変更される可能性があります(市場への適応/メカニックに対する新しい要求など)。では、 を改善するために何を考案できるでしょうか? バス係数 上記の問題に対処するための可能な解決策の 1 つとなるフローをたどってみます。 要件とRFC まず、利害関係者の要件に基づいて初期設計を説明し、それを文書化する必要があります。その後、このドキュメントを他のチームと共有し、フィードバックを要求できます。たとえば、特定の機能の実装を依頼したり、初期設計についてコメントしたり、特定のインターフェースを修正したりします。このようなドキュメントは 呼ばれます。 RFC と (Request for Comments)は、開発者、設計者、その他のチームを含む関係者間で配布され、フィードバック、コメント、提案を収集する文書です。仕様ほど詳細ではなく、初期の問題、タスク、およびソリューション ドメインのみが含まれます。より柔軟性が高いため、設計の変更を積極的に受け入れることができ、タスクを深く理解し、質の高い思慮深い意思決定を促進します。 RFC 設計コミットメントとADR さて、 、 。次は何でしょうか? 技術要件を定義し 他のチームからの要件を収集しました この段階では、 必要があります。この目的のために、 作成します。 システム設計とそれが実行するすべての主要機能を最終決定する ADR を (アーキテクチャ決定記録) は、ソフトウェア開発プロセス中に行われた重要なアーキテクチャ上の決定を記録する文書です。各 には、特定の高レベルのアーキテクチャ上の決定、そのコンテキスト、検討された代替案、下された決定、および他の詳細よりもこれらの特定の詳細を選択した理由が記述されています。 ADR ADR このようなドキュメントにより、すべてのチーム メンバー (および他のチーム) が設計の基盤となる原則と価値 になります。数年後に新しい開発者がチームに参加し、「なぜこのようにしたのですか?」と尋ねられた場合、このドキュメントを提示することで、すべての質問に答えることができます。 を理解できるよう 仕様 次は、コードとその仕様を記述する段階です。この段階では、各機能を徹底的に検討し、同時にすべての情報と実装の詳細を特別なドキュメントにまとめます。このドキュメントには、システムの現在の低レベルの要件が反映されている必要があります。 :ソフトウェアのライフサイクル中に、このような仕様は大幅に変更される可能性がありますが、それは問題ありません。ただし、コードベースが管理不能にならないように、元の設計とアーキテクチャを維持することが非常に重要です。 重要なポイント テスト計画 なぜ必要なのでしょうか。テスト プランは、仕様に従って記述された 、 必要 重要なシナリオを含む 構築することが重要です。また、このようなテスト プランを他のチームにレビュー用に提出して (統合用または追加のテスト用)、さまざまな状況でシステムがどのように動作するかを明確にすることも非常に便利です。 コード (コードを作成し、このコードが合格するようにテストします) に基づいて構築するのではなく 正しく処理する がある 設計に基づいて 何が含まれていますか? あらゆるシステム運用シナリオ ハッピーパス 悲しい道 エラー処理 システム運用中に維持する必要があるすべての不変条件 開始時にシステムの状態を確認するための受け入れテスト(ネットワーク上のデータなどの環境を考慮する必要があります) を確定し、コードと を書き、 をまとめました。すでにかなりしっかりした感じですが、他に何を追加できるでしょうか? 設計 仕様 テスト計画 展開計画 このような計画は 、チームメンバーがシステムを展開してその状態を確認できる条件を作成するために、ある程度必要になる可能性があります。 、バス係数を改善し なぜそれがないのでしょうか? なくてもできますが、現実の世界では、システムのさまざまな部分に多くの人が責任を負っている大規模なチームがあり、デプロイメント プロセスは DevOps に 可能性があります。テストを記述し、CI に配置し、脆弱性をチェックしているので、他に何か必要なのでしょうか? おそらくそうではないかもしれませんが、多くの場合、テストはシステムの現在の状態を考慮せず、私たちが望むものとはまったく異なるテストになります。 完全に委任されている 展開計画には次の 。 内容が含まれます 展開を実行するために実行する必要があるアクションの完全な説明 展開パラメータ: 環境変数 初期状態 打ち上げパラメータ どの段階でも何か問題が発生した場合の計画 可能であればバックアッププラン 展開の継続が不可能な場合にシステムを到達させる必要のある状態 展開後に実行する必要があるアクション 他のチームに通知する 必要に応じて必要な統合を有効にする 何も複雑なことではないですよね? 特定の更新に関するこのようなドキュメントがあれば 、特定の個人への ができます。それが私たちが望んでいることではないでしょうか? 、バス係数が大幅に向上し 依存を防ぐこと 結論 ソフトウェア開発プロセスでは、コードを書くだけでなく、開発の全段階を通じて理解と一貫性を確保するドキュメントを作成することも重要です。ドキュメントは が、経験上、特に開発中にチームが変更された場合や、プロジェクトが進化して新しい要件に適応する場合、システムの品質、安定性、将来の拡張性を維持するためにドキュメントが非常に重要であることがわかっています。 コード自体である場合もあります ドキュメントには、 (Request for Comments)、 (Architecture Records)、 、 、 などが含まれます。これにより 保証され、 プロセスが簡素化され、 。 RFC ADR 仕様 テスト計画 展開計画 、チーム内での知識の保持が 新しい従業員をプロジェクトに統合する システム全体の信頼性と変更に対する耐性が向上します