私は中規模プロジェクトの途中に参加しました。このプロジェクトはすでに数年にわたって実行されています。問題の1つは、アーキテクチャを説明するドキュメントが記述されていないことです。これで、アーキテクチャー記述を作成するタスクが割り当てられました。

このプロジェクトに取り組んでいる間、ドキュメントを書くために必要なすべての情報を収集しました。いくつかの機能も追加したので、説明したとおりにアーキテクチャを明らかに破壊しているコードをいくつか特定しました。

たとえば、GUIはビジネスロジックのない薄いレイヤーであると想定されていました。それが私に言われたことです。実装には多くのロジックが含まれています。

上司がタスクを割り当てて、システムのアーキテクチャを説明するドキュメントを作成しました。対象読者は、プロジェクトに取り組んでいる現在および将来の開発者です。どうあるべきかを説明する必要がありますが、どういうわけか偏差も説明する必要があります。

それでは、これらの問題をどこで説明すればよいのでしょうか？バグ追跡ソフトウェア？または、システムのアーキテクチャを説明するドキュメントで、アーキテクチャからの実装の逸脱を説明する必要がありますか？

すでに構築されているシステムの設計またはアーキテクチャを文書化する場合、文書には、設計どおりまたは意図されたものではなく、構築されたものを記述する必要があります。アーキテクチャに奇妙な点や食い違いがある場合は、このドキュメントでそれらの問題を指摘し、読者に可能な限り説明する必要があります。

最初からシステムに取り組んでいる（または少なくともあなたが持っているよりも長い）人から情報を取得できる場合、実際に何が意図されていたのか、なぜアーキテクチャと設計がこれから逸脱したのかについて、より多くの情報を取得することが有用です意図。

結局のところ、設計文書はコードのガイドとして役立つはずです。ドキュメントが、新しい開発者がコードベースの現在の状態とその構造を理解するのに役立たない場合、ドキュメントは役に立ちません。

このドキュメントは、システムへの変更の将来の計画と設計をガイドし、開発プロセス内で適宜更新するために使用される生きたドキュメントである必要があります。設計が時間とともに変化し進化するにつれて、このドキュメントは、開発者が現在の状況を理解するのに役立つはずです。

アーキテクチャのキャプチャに関するアドバイスを探しているなら、IEEE Standard 1016-2009 IEEE Standard for Information Technology-Systems Design-Software Design Descriptionで提唱されているアプローチが好きです。これは、設計記述の合理的な構造を提供し、アーキテクチャおよび詳細レベルの設計情報の両方をキャプチャするために使用できます。

また、これらの逸脱は技術的負債の一形態であると考えます。問題を解決するのは大規模な取り組みかもしれませんし、おそらく小さなプロジェクトかもしれませんが、技術的負債の存在をより明確にすることをお勧めします。欠陥追跡ツールを使用することを意味する場合、そこに1つ以上の問題を配置できます。ソフトウェアの提案や機能拡張を追跡するために使用する別のツールがある場合、それは別の場所にある可能性があります。

システムのアーキテクチャを形式化するとき、アーキテクチャがテーブルにもたらすものの背後にある価値を理解するだけでなく、それがどうあるべきかを理解し、認識することも重要です。

ソフトウェアまたはテクニカルアーキテクチャの主な目標は、システムアーキテクチャを推進する品質属性によって実現される非機能要件を特定することです。

非機能要件について：

非機能要件は、特定の動作ではなく、システムの動作を判断するために使用できる基準を指定する要件です。特定の動作や機能を定義する機能要件とは対照的です。機能要件の実装計画は、システム設計で詳しく説明されています。非機能要件を実装するための計画は、システムアーキテクチャで詳しく説明されています。

概して、機能要件はシステムの動作を定義し、非機能要件はシステムの動作を定義します。...非機能要件は、しばしばシステムの「品質属性」と呼ばれます。非機能要件の他の用語は、「品質」、「品質目標」、「サービス品質要件」、「制約」、および「非動作要件」です。

もちろん、グリーンフィールドプロジェクトでは、アーキテクチャ的に重要な要件を特定することは理にかなっていますが、既存のソフトウェアを使用する場合は、できる限り規律を守ることが最善です。ソフトウェアアーキテクチャが既存のシステムの影響を受けないようにする必要があります。

信頼できるソフトウェアアーキテクチャは、本当に3つのものである必要があります。

宣言的

これはドキュメンテーションの一部であり、「何ではない」と宣言しますが、どのようにすべきかを宣言します。これは、システムのさまざまなアーキテクチャビューを使用して行います。必要なコンポーネントとそれらの相互作用を定義し、オプションで各コンポーネントにドリルダウンして、システムの設計方法を宣言するより詳細なビューを作成します。

これは重要な違いです。システム設計は、システムアーキテクチャによって制約される必要があります。これらは実際には別個のものですが、関連するものです。

根拠

ソフトウェアアーキテクチャの根拠は、行われたアーキテクチャの決定に正当性と権限を与えるものです。おそらく、バッチジョブをトリガーするためにMQでPub / Subイベントリスナーを使用することを決定し、それを図にしたのでしょうか？

なぜこの決定が下されたのですか？理由のセクションで理由を説明し、説明を非機能要件、品質属性目標、または建築的に重要な要件にリンクします。（たとえば、ジョブは非同期で繰り返し可能である必要があり、品質属性としての保守性により、バッチジョブに障害が発生した場合にMQメッセージを介してジョブを再開できるようになります。 ..）

リスク

アーキテクチャのあり方を宣言し、それを根拠で証明したので、システムの現在の状態に関するリスクを特定できます。

（たとえば、サーバー側の検証がクライアント側のJavascriptコードで複製されています。これはDRY原則に違反しており、保守性の品質属性に反します。この領域のパフォーマンスに関する非機能要件は定義されていません。現在のシステムの動作に対する根拠はありません）

リスクは、現在の状態が現在アーキテクチャから逸脱している場所を示すこともできます。これらのリスクは、プロジェクトプランを通じて、またはこれをバックログに追加することにより、開発チームがすぐに対処できます。

プロジェクトの現在の構造、プロジェクトの目的の構造、またはその両方を文書化することになっているのかどうかを決定する必要があります。

目的のラインに沿って将来の開発をガイドする目的で目標を文書化し、バグとして偏差を上げることができます（おそらく、文書の関連部分からこれらのバグにリンクします）。または、コードの概要/概要を提供するために、現実を文書化することもできます。それとも、あなたは同時に、将来の開発のためのガイド持っているように、両方のサイド・バイ・サイドを文書化できかつ一箇所における現在のコードの正確な説明を。文書の目的に応じてすべてが合理的であるため、どの文書を実行すべきかを有用に伝えることはできないと思います。

また、目的のアーキテクチャが関係者の間で普遍的に合意されていない可能性があることを心に留めておく必要があります目標から外れます）。そのため、あなたが望むものを決定する権限を持っているかどうか、そして誰がそうしていないかを知る必要もあります。既存の構造には、少なくとも1つしか文書化できないという長所があります！

想定されるアーキテクチャ設計ドキュメントに記述し、各競合について、競合を説明するバグトラッカーのチケットを開きます。チケットのコメントセクションでは、関係者が特定の競合について議論するためのプラットフォームを提供します。

これらの各チケットの解決策は、設計に合わせて実装を変更することですが、実装に合わせて設計を変更することもできます。理想的には前者が好まれますが、技術的および/またはビジネス上の制約により、後者を選択するのがより効率的/実用的/可能になる場合があります。その場合、アーキテクチャ設計ドキュメントからチケットを参照することをお勧めします。これにより、その特定の下位デザインの選択が選ばれた理由を理解していない将来の読者は、チケットの議論を読んで背後にある理由を理解できますそれ。

3つの主要なセクションに分かれた建築文書を書きたいと思います。

最初に意図された設計/アーキテクチャの最初の紹介。これにより、新しい開発者/読者は、システムが何をすべきかについてのアイデアを得ることができ、明らかに要件/ユースケースなどに結び付けられるべきです。

2番目のセクションでは、アーキテクチャが実際に何であるかを非常に明確に説明する必要があります。これにより、新しい開発者/読者は、ソフトウェア（および潜在的に他のドキュメント）を見ると、現在のプレイの状態と、彼らが何を扱っているかを知ることができます。このセクションでは、意図したものと現実の違いを明確に示す必要があります。これにより、元のアーキテクチャで非常に間違っている（できれば多すぎることはありません！）開発チームに大きなプレッシャーがかかっている）、要件が満たされていないか、ソフトウェアが「粗末」に設計されているように見え始めています。

最後に、今何をする必要があるかについての推奨事項を詳述するセクションを考えます。これは、あなたのビジョンを現実のものにするために、現在のアーキテクチャ/設計の変更とソフトウェアの変更のロードマップでなければなりません。

これは、キャプチャする必要があるものを（高レベルで）カバーしていると思います。文書のサブセクションまたは使用するバグ追跡ソフトウェアの観点からこれをどのように行うかは、作業しているドメイン/個人の好み/チームの規模/予算/タイムスケールなどにかかっています。