設計書作成と作業形骸化

「マイクロソフト系技術情報 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: :ドキュメンテーション, :その他、開発の色々