Open棟梁Project - マイクロソフト系技術情報 Wiki

* 目次 [#l667ed72]
#contents

*概要 [#qe09faeb]
ソースコード・[[ドキュメンテーション・ツール]]の利用事例を紹介します。
ソースコード・[[ドキュメンテーション・ツール]]の利用例を紹介します。

*参考 [#y86fa3cf]
-[[ドキュメンテーション・ツール]]
-[[使用APIの一覧、関数コールグラフ、単体テストのエビデンス]]

-[[リエンジ用途でリバース・ツールを利用]]
-[[提案するドキュメント標準化ワークフロー]]

*フォワードとリバースの事例 [#p3adf6f6]
某案件では、

-フォワード（モジュールレベルの詳細設計書作成）と
-リバース（モジュールからドキュメント生成）の

両面を採用しました。

内作し担当者のスキルが把握できていれば、完全リバースでもリスクは低いと思いますが、~
設計者のスキルが把握できていれば、完全リバースでもリスクは低いと思いますが、~
そうでない場合は製造する対象物(ファイル、クラス、メソッド、その概要、等)を~
明確にししないと、製造物の進捗も管理できませんし、設計能力も量れません。

国内/国外パートナー に発注を前提とする場合は、リスクを考慮した場合、~
製造する対象物(ファイル、クラス、メソッド、その概要、等)は明確にした方が良いと思います。

そうしないと、

-製造物の進捗も管理できませんし、
-パートナーの設計能力も量れません

ので。

*フォワードの事例 [#jdbdcd23]
**問題 [#c0cfb12b]
某案件では、フォワード（モジュールレベルの詳細設計書作成）の際にやり過ぎて、
-工程を圧迫し、品質が問題になりました。
-また、設計書を作る（＝こなす）のが目的になってしまい、作業の形骸化が起こってしまいました。

**分析 [#b1730246]
-クラス・メソッド仕様書記述の意味合いも良く検討する。~
従来の手法は、設計に時間をかけて品質を出しているに過ぎない。

--具体的な事例に、1stepに対応する仕様書を書くという方法がある。
--顧客予算が対応しなければ成立しない方法（工程を圧迫）

-IDEを使用してモジュールのスケルトンを作成し~
[[ドキュメンテーション・ツール]]でリバースするという方式も考えられる。
--業務レベルの設計を行う人間にモジュール設計まで担当させるのは難しい。
--どの道、プログラム・レベルの設計で覆されるのが落ちである。

**イベントフロー、アクティビティ図（≒フローチャート）の事例 [#bf1f9a49]
***問題 [#o29824d5]
ここまでやる場合は、イベントフロー、アクティビティ図（≒フローチャート）から~
ソースコードを自動生成する位は考えないと、生産性が上がらないと思います。

一度 Word、Exel で設計するプロジェクトに採用しましたが、~
修正や設計に手間がかかる割には、製造・テスト工程の生産性は上がらず、~
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下がりました。

***対策 [#lfd8d51b]
「ソースコードを自動生成する位は考えないと、生産性が上がらないと思います。」

上記の見解について、

-構造化言語というツールもあるが、仕様書は自然言語で記述されることが多い。
--自然言語で問題ないため、ワザワザ他のツールを導入する動機が無い。

-UML（イベントフロー、アクティビティ図）などを納品物として作成する場合、~
これら重複が自然言語で書かれたドキュメント
--の何を代替するのか？
--と比べ優れているか劣っているか？

を考える必要がある。

一部業務アプリケーション開発の用途でも効果的な活用方法は発見されている。

-シーケンス図（アーキテクチャ説明、モジュール構成説明）
-状態遷移図（状態ごとの制御が複雑なプログラムの説明）
-ディシジョン・テーブル or ツリー（ディシジョンの説明）

従って、~

上記の様な自然言語で表し難い仕様を説明する~
表記方法については、補足説明書として付属させても良い。

*リバースの事例 [#mafe6bac]
比較的多くの案件で採用されている。~
（業務的詳細設計書と方式設計書をコーディング工程で結合する）~
モジュールレベルの詳細設計書はリバース生成させる。

**問題 [#xd872266]
Doxygenを採用（A Hot Document等で代替も可能）し、~
メソッド内コメントのコメント規則を整備して~
設計書をリバース生成させる方式を導入したが定着せず。~

**分析 [#o7e4e5b2]
理由は以下

-イベント仕様書記述（業務的詳細設計書）で足りる~
（わざわざリバース生成する必要が無い）
-イベント仕様書記述（業務的詳細設計書）で足りる（わざわざリバース生成する必要が無い）

-リエンジ用途（リエンジの詳細は後述）
--としては不完全
--としては不完全である。
--として活用するのは先（将来）の話になってしまう。

-以下の様に、コメントの振り方が変わってきてしまう。
--以下がプログラム内に混在
---内部文書化目的のコメント（一般的なコメント）
---リバース生成目的のコメント

--このため、メソッド冒頭にメソッド仕様を~
纏めて記述するなどした方が良い。
--このため、メソッド冒頭にメソッド仕様を纏めて記述するなどした方が良い。

A Hot Documentも納品・保守ドキュメント生成と割り切っている。~
http://www.hotdocument.net/

製品など、ドキュメントを納品ではなく自分のために使用する場合は、~
リバース生成方式の採用を本格的に検討しても良いかもしれない。
リバース生成方式の採用を本格的に検討しても良いかもしれません。

**モジュールレベルの詳細設計書の納品を求められるケース [#rd8e07ed]

必要不可欠というものではなく、作業形骸化を起こすため問題が多い。~

前述の[[イベントフロー、アクティビティ図>#bf1f9a49]]で説明したとおり、

>修正や設計に手間がかかる割には、製造・テスト工程の生産性は上がらず、~
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下がりました。

という状態に陥ることになる。

これでも、クラス・メソッド仕様書を
これでも、クラス・メソッド仕様書を納品物として求められることがある。
-リバース・ツールの生成する形式ではなくExcel形式で要求される。
-手書きでフォワードしたもののみ認められる見積条件の場合も。

-納品物として求められることがある。
-リバース・ツールの生成する形式ではなくExcel形式で要求される。~
--このため、A Hot DocumentはExcel形式の生成もサポート。
--手書きでフォワードしたもののみ認められる見積条件の場合も。

というケースが後を絶たないのは、~
商習慣（見積条件）によるところが大きいと考える。~

また、この商習慣（見積条件）は、
>[[リバースの事例>#mafe6bac]]での記述とは別の理由で

リバース生成が採用されない理由の一つにもなっている。

**[[リエンジ用途でリバース・ツールを利用]] [#kd670643]
だいたいNG。リンク先を参照ください。

*[[提案するドキュメント標準化ワークフロー]] [#vfc816e3]
ご参考。リンク先を参照ください。
トップ   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS