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