マイクロソフト系技術情報 Wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。

目次

概要

  • 基本的に、設計作業や、その後のテスト作業に必要となる
    仕様書・設計書の類は、リバースせず設計者によりブレークダウンする。
  • Windows Forms, Web Formsなど
    • 画面単位のモジュール化
    • コンポーネントベース
    • イベント・ドリブン

などを実現するフレームワークを活用する場合、詳細設計作業以降のモジュール設計作業の形骸化が発生することがある。
(MVCなどの柔軟性の高いフレームワークを使用する場合、モジュール設計作業工程が重要になるケースもある。
大規模開発でMVCが標準のJavaを使用するケースなどでは、モジュール設計書から、スケルトンの自動生成をしている事が多い。)

  • フレームワークによっては、ブレークダウンの作業が形骸化してしまう類の
    ドキュメント(特に、クラス・メソッド一覧系や、クラス・メソッド定義書系)
    のみドキュメンテーション・ツールを適用してリバースする。

フォワードとリバースの事例

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

両面を採用する理由としては、進捗管理や設計能力の確認などが含まれるようです。

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

フォワードの事例

問題

フォワード(モジュール・レベルの詳細設計書作成)の際にやり過ぎて、

  • 工程を圧迫し、品質が問題になった。
  • また、設計書を作る(=こなす)のが目的になってしまい、作業の形骸化が起こった。

という問題が事例ベースで報告されていますが、
こういった作業経験がある方は、想像に難くない内容かと思います。

分析

  • クラス・メソッド仕様書記述の意味合いも良く検討する。
    従来の手法は、設計に時間をかけて品質を出しているに過ぎない。
  • 具体的な事例に、1stepに対応する仕様書を書くという方法がある。
  • 顧客予算が対応しなければ成立しない方法(工程を圧迫)
  • IDEを使用してモジュールのスケルトンを作成し
    ドキュメンテーション・ツールでリバースするという方式も考えられる。
    • 業務レベルの設計を行う人間にモジュール設計まで担当させるのは難しい。
    • どの道、プログラム・レベルの設計で覆されるのが落ちである。

イベントフロー、アクティビティ図(≒フローチャート)の事例

問題

ここまでのフォワード(モジュール・レベルの詳細設計書作成)を実施した案件からは、
イベントフロー、アクティビティ図(≒フローチャート)などからソースコードを
自動生成する位は考えないと、生産性が上がらないという意見も出ています。

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

対策

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

上記の見解について、

  • 構造化言語というツールもあるが、仕様書は自然言語で記述されることが多い。
    • 自然言語で問題ないため、ワザワザ他のツールを導入する動機が無い。
  • UML(イベントフロー、アクティビティ図)などを納品物として作成する場合、
    これら重複が自然言語で書かれたドキュメント
    • の何を代替するのか?
    • と比べ優れているか劣っているか?

を考える必要があるかと思います。

一部、業務アプリケーション開発の用途でも効果的なダイアグラムもあります。

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

従って、上記の様な自然言語で表し難い仕様を説明する
これらのダイアグラムを必要に応じて作成する場合は、
補足説明書として付属させても形骸化は発生しません。

リバースの事例

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

問題

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

分析

理由は以下

  • イベント仕様書記述(業務的詳細設計書)で足りる(わざわざリバース生成する必要が無い)
  • リエンジ用途(リエンジの詳細は後述)
    • としては不完全である。
    • として活用するのは先(将来)の話になってしまう。
  • 以下の様に、コメントの振り方が変わってきてしまう。
    • 以下がプログラム内に混在
      • 内部文書化目的のコメント(一般的なコメント)
      • リバース生成目的のコメント
  • このため、メソッド冒頭にメソッド仕様を纏めて記述するなどした方が良い。

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

モジュール・レベルの詳細設計書の納品を求められるケース

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

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

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

という状態に陥ることになります。

これでも、クラス・メソッド仕様書を納品物として求められることがある。

  • リバース・ツールの生成する形式ではなくExcel形式で要求される。
  • 手書きでフォワードしたもののみ認められる見積条件の場合も。

リエンジ用途でリバース・ツールを利用

だいたいNG。リンク先を参照ください。


Tags: :ドキュメンテーション, :その他、開発の色々


トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2017-06-13 (火) 15:27:47 (617d)