Open棟梁 wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。

目次

概要

ドキュメント標準のポイント

ドキュメント標準化ワークフロー

設計ドキュメントの標準化のためのワークフロー概要図

1

ドキュメンテーション

設計書作成と作業形骸化

Windows Forms, Web Formsなど

  • 画面単位のモジュール化
  • コンポーネントベース
  • イベント・ドリブン

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

ドキュメンテーション・ツール

  • 納品、保守用のプロダクト
  • マニュアル生成用のOSS
  • ソースコード解析ツール

などは存在するが、

リエンジ用のドキュメント生成用途にはあまり適合しない。
前述の「設計書作成と作業形骸化」の防止に利用できる。

処理説明のリバース出力

  • プログラム設計レベルのフローチャートでは、条件分岐数が多くなりすぎ、
    フローチャートを一見して、詳細設計内容を理解することは難しいと考える。
  • このため、モジュールに詳細設計レベルの説明を付与するには、
    ドキュメンテーション・ツールのメソッド中コメントを使用して、
    メソッド定義書の「処理説明」に詳細設計内容を出力すると良いと考える。

※ メソッド中コメントが入っていないプログラムでは
メソッド定義書の「処理説明」欄に詳細設計内容を出力できないので注意する。

A HotDocument?

  • A HotDocument?のメソッド中コメントのコメント ルールは単純で、
    コメントを「///」で開始することでメソッド中コメントを記述でき、
    コメント文字「/」を1つ増やすことによって字下げが可能になっている。
  • メソッド中コメント記述の際は、メソッド定義書に出力される
    「処理説明」の見易さなどを意識する必要がある。
2-1

サンプル プログラム

2-2

Excel出力例

2-3

HTML、ヘルプ ファイル出力例

2-4

参考

Doxygen

  • /*! ~コメント~ */を使用すれば、メソッド定義書に出力できる。
  • ただし、A HotDocument?と同様にメソッド中コメント記述の際は、
    メソッド定義書に出力される「処理説明」の見易さなどを意識する必要がある。

出力例

2-5

参考

進捗の管理方法

  • 設計書作成と作業形骸化で説明したような理由で、詳細設計作業以降の
    モジュール設計作業工程の成果物を作成しない場合、モジュール設計作業工程の進捗管理が困難になる。
3

参考

OSSコンソーシアム

Think IT(シンクイット)

即活用!業務システムの開発ドキュメント標準化

記事一覧
https://thinkit.co.jp/series/6536

令和時代のシステム開発では、どのような設計書を書くべきか

記事一覧
https://thinkit.co.jp/series/9344

日経 xTECH(クロステック)

読み手が納得する開発ドキュメントの作り方

https://tech.nikkeibp.co.jp/atcl/nxt/column/18/01054/

「要件は現行通り」と言われ困惑、ドキュメントが無いIT職場の悲惨な現状

https://tech.nikkeibp.co.jp/atcl/nxt/column/18/00205/012000026/

変わらない開発現場


添付ファイル: file2-5.png 318件 [詳細] file2-4.png 265件 [詳細] file2-3.png 440件 [詳細] file2-2.png 341件 [詳細] file2-1.png 379件 [詳細] file3.png 273件 [詳細] file1.png 324件 [詳細]

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2020-02-06 (木) 12:01:05 (12d)