![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicrosofttech.osscons.jp/]]」は、「[[Open棟梁Project>https://github.com/OpenTouryoProject/]]」,「[[OSSコンソーシアム .NET開発基盤部会>https://www.osscons.jp/dotNetDevelopmentInfrastructure/]]」によって運営されています。 -[[戻る>ドキュメンテーション]] * 目次 [#l667ed72] #contents *概要 [#qe09faeb] -基本的に、設計作業や、その後のテスト作業に必要となる~ 仕様書・設計書の類は、リバースせず設計者によりブレークダウンする。 -Windows Forms, Web Formsなど --画面単位のモジュール化 --コンポーネントベース --イベント・ドリブン >などを実現するフレームワークを活用する場合、詳細設計作業以降のモジュール設計作業の形骸化が発生することがある。~ （MVCなどの柔軟性の高いフレームワークを使用する場合、モジュール設計作業工程が重要になるケースもある。~ 大規模開発でMVCが標準のJavaを使用するケースなどでは、モジュール設計書から、スケルトンの自動生成をしている事が多い。） -フレームワークによっては、ブレークダウンの作業が形骸化してしまう類の~ ドキュメント（特に、クラス・メソッド一覧系や、クラス・メソッド定義書系）~ のみ[[ドキュメンテーション・ツール]]を適用してリバースする。 *フォワードとリバースの事例 [#p3adf6f6] -フォワード（モジュール・レベルの詳細設計書作成）と -リバース（モジュールからドキュメント生成）の 両面を採用する理由としては、進捗管理や設計能力の確認などが含まれるようです。 「設計者のスキルが把握できていれば、完全リバースでもリスクは低いと思いますが、~ そうでない場合は製造する対象物(ファイル、クラス、メソッド、その概要、等)を~ 明確にししないと、製造物の進捗も管理できませんし、設計能力も量れません。」 *フォワードの事例 [#jdbdcd23] **問題 [#c0cfb12b] フォワード（モジュール・レベルの詳細設計書作成）の際にやり過ぎて、 -工程を圧迫し、品質が問題になった。 -また、設計書を作る（＝こなす）のが目的になってしまい、作業の形骸化が起こった。 という問題が事例ベースで報告されていますが、~ こういった作業経験がある方は、想像に難くない内容かと思います。 **分析 [#b1730246] -クラス・メソッド仕様書記述の意味合いも良く検討する。~ 従来の手法は、設計に時間をかけて品質を出しているに過ぎない。 --具体的な事例に、1stepに対応する仕様書を書くという方法がある。 --顧客予算が対応しなければ成立しない方法（工程を圧迫） -IDEを使用してモジュールのスケルトンを作成し~ [[ドキュメンテーション・ツール]]でリバースするという方式も考えられる。 --業務レベルの設計を行う人間にモジュール設計まで担当させるのは難しい。 --どの道、プログラム・レベルの設計で覆されるのが落ちである。 **イベントフロー、アクティビティ図（≒フローチャート）の事例 [#bf1f9a49] ***問題 [#o29824d5] ここまでのフォワード（モジュール・レベルの詳細設計書作成）を実施した案件からは、~ イベントフロー、アクティビティ図（≒フローチャート）などからソースコードを~ 自動生成する位は考えないと、生産性が上がらないという意見も出ています。 「一度 Word、Exel で設計していたプロジェクトにこれらを採用しましたが、~ 修正や設計に手間がかかる割には、製造・テスト工程の生産性は上がらず、~ むしろ、設計書の修正が追いつかずプロジェクトの完成度が下がりました。」 ***対策 [#lfd8d51b] 「ソースコードを自動生成する位は考えないと、生産性が上がらないと思います。」 上記の見解について、 -構造化言語というツールもあるが、仕様書は自然言語で記述されることが多い。 --自然言語で問題ないため、ワザワザ他のツールを導入する動機が無い。 -UML（イベントフロー、アクティビティ図）などを納品物として作成する場合、~ これら重複が自然言語で書かれたドキュメント --の何を代替するのか？ --と比べ優れているか劣っているか？ を考える必要があるかと思います。 一部、業務アプリケーション開発の用途でも効果的なダイアグラムもあります。 -シーケンス図（アーキテクチャ説明、モジュール構成説明） -状態遷移図（状態ごとの制御が複雑なプログラムの説明） -ディシジョン・テーブル or ツリー（ディシジョンの説明） 従って、上記の様な自然言語で表し難い仕様を説明する~ これらのダイアグラムを必要に応じて作成する場合は、~ 補足説明書として付属させても形骸化は発生しません。 *リバースの事例 [#mafe6bac] 比較的多くの案件で採用されている。~ （業務的詳細設計書と方式設計書をコーディング工程で結合する）~ モジュール・レベルの詳細設計書はリバース生成させる。 **問題 [#xd872266] Doxygenを採用（A Hot Document等で代替も可能）し、~ メソッド内コメントのコメント規則を整備して~ 設計書をリバース生成させる方式を導入したが定着せず。~ **分析 [#o7e4e5b2] 理由は以下 -イベント仕様書記述（業務的詳細設計書）で足りる（わざわざリバース生成する必要が無い） -リエンジ用途（リエンジの詳細は後述） --としては不完全である。 --として活用するのは先（将来）の話になってしまう。 -以下の様に、コメントの振り方が変わってきてしまう。 --以下がプログラム内に混在 ---内部文書化目的のコメント（一般的なコメント） ---リバース生成目的のコメント --このため、メソッド冒頭にメソッド仕様を纏めて記述するなどした方が良い。 製品など、納品やリエンジ用途ではなく自分のために使用する場合は、~ リバース生成方式の採用を本格的に検討しても良いかもしれません。 **モジュール・レベルの詳細設計書の納品を求められるケース [#rd8e07ed] 必要不可欠というものではなく、作業形骸化を起こすため問題が多い。~ 前述の[[イベントフロー、アクティビティ図>#bf1f9a49]]で説明したとおり、 >「修正や設計に手間がかかる割には、製造・テスト工程の生産性は上がらず、~ むしろ、設計書の修正が追いつかずプロジェクトの完成度が下がりました。」 という状態に陥ることになります。 これでも、クラス・メソッド仕様書を納品物として求められることがある。 -リバース・ツールの生成する形式ではなくExcel形式で要求される。 -手書きでフォワードしたもののみ認められる見積条件の場合も。 **[[リエンジ用途でリバース・ツールを利用]] [#kd670643] だいたいNG。リンク先を参照ください。 ---- Tags: [[:ドキュメンテーション]], [[:その他、開発の色々]]
