アーキテクチャ設計の文書化戦略

Question

現在の段階までソフトウェアプロジェクトを文書化しようとしています。読者層は自分自身（将来の）、他の開発者（現在および短期間の将来）、およびエンドユーザーを含むでしょう。したがって、ドキュメントには、設計要件、アーキテクチャ/設計（データ構造、アーキテクチャ、ユーザーインターフェイス、手続き型設計）、技術文書、およびエンドユーザーの説明が記載されています。文書は、いくつかの歴史的記録を提供するために主に生産されています。現在のところ、プロジェクトに携わっている2人のチームですが、他の人のプロジェクトの多くの機能がこのプロジェクトに追加されるため、短期間で多くの人が参加する可能性があります。

私が問題を抱えているのは、建築設計文書（http://en.wikipedia.org/wiki/Design_document）です。 doxygenを使ってある種のデータフロー図を作成しようとしたが、それは容易ではなかった。 C++コードからデータフロー図を生成するツールがあれば簡単ですか？これはMicrosoft Visioで手動で描画する場合ですか？前もって感謝します。

Answer 1

ソースコードから自動的に生成された低レベルの図は役に立たなくなります。彼らはより多くあなたのコードよりも曖昧で、乱雑な視覚的レイアウトを持っていて、すぐに古くなってしまいます。将来の開発者はそれらを信用して代わりにコードを見るので、ソースコードのリファクタリング（つまり、自明の名前を使用する、問題のドメインをきれいに表すクラス構造を持たせるなど）に）。

良いjavadocまたはdoxygenコメントを作成し、最新の状態に保つことは価値があります。多くの人がこれを非常に便利だと感じています。

ハイレベルの図も重要です。 Martin FowlerのUML Distilledを読んで、UML表記を学んでください。その後、Visoや他のグラフィカルエディタを使用して、ソフトウェアの一部だけをドキュメント化し、将来の開発者に役立ててください。ダイアグラムを「完全」かつ完璧なものにする時間を無駄にしないで、他の開発者にとって最も役立つものに集中してください。

Answer 2

建築家のエディションのコンポーネントを含むVisual Studio Team Suiteの試用版をダウンロードできます。

Answer 3

ツールでコードを文書化する前に、コードを読み取る必要があります。

コードを読むことは、「リバースエンジニアリング」とも呼ばれます。

コードは、さまざまなツールでリバースエンジニアリングすることができます。このツールは、そのコードのUML図を作成できます。残念ながら私がこれを数年前に試してみたところ、リバースエンジニアリングのC＃で偉大な仕事をするいくつかのツールは、リバースエンジニアリングのレガシーC++で不完全な仕事をしていることが分かりました（C++は解析が難しく、 -OOグローバル関数など）。

Googleを「リバースエンジニア」または「ラウンドトリップ」という用語で「C++」、「UML」または「図」と組み合わせて使用​​すると、多くのツールを見つけることができます。

マイクロソフトは改良されたC++ツールを約束していますが、そのタイムラインが何であるかわかりません。