Open棟梁Project - マイクロソフト系技術情報 Wiki
目次 †
フォワードとリバースの事例 †
某案件では、
- フォワード（モジュールレベルの詳細設計書作成）と
- リバース（モジュールからドキュメント生成）の
両面を採用しました。
内作し担当者のスキルが把握できていれば、完全リバースでもリスクは低いと思いますが、
国内/国外パートナー に発注を前提とする場合は、リスクを考慮した場合、
製造する対象物(ファイル、クラス、メソッド、その概要、等)は明確にした方が良いと思います。
そうしないと、
- 製造物の進捗も管理できませんし、
- パートナーの設計能力も量れません
ので。
フォワードの事例 †
問題 †
某案件では、フォワード（モジュールレベルの詳細設計書作成）の際にやり過ぎて、
- 工程を圧迫し、品質が問題になりました。
- また、設計書を作る（＝こなす）のが目的になってしまい、作業の形骸化が起こってしまいました。
分析 †
- クラス・メソッド仕様書記述の意味合いも良く検討する。
従来の手法は、設計に時間をかけて品質を出しているに過ぎない。
- 具体的な事例に、1stepに対応する仕様書を書くという方法がある。
- 当然の事ながら、顧客予算が対応しなければ成立しない方法である（工程を圧迫）
- IDEを使用してモジュールのスケルトンを作成し
ドキュメンテーション・ツールでリバースするという方式も考えられる。
- 業務レベルの設計を行う人間にモジュール設計まで担当させるのは難しい。
- どの道、プログラム・レベルの設計で覆されるのが落ちである。
リバースの事例 †
比較的多くの案件で採用されている。
（業務的詳細設計書と方式設計書をコーディング工程で結合する）
モジュールレベルの詳細設計書はリバース生成させる。
問題 †
Doxygenを採用（A Hot Document等で代替も可能）し、
メソッド内コメントのコメント規則を整備して
設計書をリバース生成させる方式を導入したが定着せず。
分析 †
理由は以下
- イベント仕様書記述（業務的詳細設計書）で足りる
（わざわざリバース生成する必要が無い）
- リエンジ用途（リエンジの詳細は後述）
- としては不完全
- として活用するのは先（将来）の話になってしまう。
- 以下の様に、コメントの振り方が変わってきてしまう。
- 以下がプログラム内に混在
- 内部文書化目的のコメント（一般的なコメント）
- リバース生成目的のコメント
- このため、メソッド冒頭にメソッド仕様を
纏めて記述するなどした方が良いかもしれない。
A Hot Documentも納品・保守ドキュメント生成と割り切っている。
http://www.hotdocument.net/
製品など、ドキュメントを納品ではなく自分のために使用する場合は、
リバース生成方式の採用を本格的に検討しても良いかもしれない。
イベントフロー、アクティビティ図（≒フローチャート）の事例 †
問題 †
ここまでやる場合は、イベントフロー、アクティビティ図（≒フローチャート）から
ソースコードを自動生成する位は考えないと、生産性が上がらないと思います。
- 注
- Web Performerなどがこの方式を取っている。
- リポジトリ・フォワードの100％自動生成。
一度 Word、Exel で設計するプロジェクトに採用しましたが、
修正や設計に手間がかかる割には、製造・テスト工程の生産性は上がらず、
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下がりました。
対策 †
「ソースコードを自動生成する位は考えないと、生産性が上がらないと思います。」
上記の見解について、
- 構造化言語（デマルコ）というツールもあるが仕様書は自然言語で問題ない。
- UML（イベントフロー、アクティビティ図）などを納品物として作成する場合、
これら重複が自然言語で書かれたドキュメント
- の何を代替するのか？
- と比べ優れているか劣っているか？
を考える必要がある。
一部業務アプリケーション開発の用途でも効果的な活用方法は発見されている。
- シーケンス図（アーキテクチャ説明、モジュール構成説明）
- 状態遷移図（状態ごとの制御が複雑なプログラムの説明）
- ディシジョン・テーブル or ツリー（ディシジョンの説明）
従って、
上記の様な自然言語で表し難い仕様を説明する
表記方法については、補足説明書として付属させても良い。
リエンジ用途でのリバース・ツール利用 †
- 上記のドキュメンテーション・ツールはリエンジ用途での利用には不完全である。
- オブジェクト指向言語では、未だ十分なリエンジ・ツールが整備されていない。
モジュールレベルの詳細設計書の納品を求められるケース †
問題が多い。
前述のイベントフロー、アクティビティ図でも説明しましたが、
修正や設計に手間がかかる割には、製造・テスト工程の生産性は上がらず、
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下がりました。
という状態に陥ることになる。
これでも、クラス・メソッド仕様書を
- 納品物として求められることがある。
- リバース形式ではなくExcel形式で要求される。
- このため、A Hot DocumentはExcel形式の生成もサポート。
- 手書きでフォワードしたもののみ認められる見積条件の場合も。
というケースが後を絶たないのは、
商習慣（見積条件）によるところが大きいと考える。
また、この商習慣（見積条件）は、
リバースの事例での記述とは別の理由で
リバース生成が採用されない理由の一つにもなっている。
提案するドキュメント標準化ワークフロー †
・・・
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
