開発ドキュメント編

第３４章　コンポーネン利用ドキュメント

３４．１　パッケージ利用解説書

対象ワークショップ

記載項目

パッケージ名
　パッケージ名、たとえば「人事システムフレームワーク」といった名前

バージョン
　パッケージのバージョン。例　Ver XX.RR
　通常、インタフェースに大きな変化がなければレビジョンアップ(RRの部分)とする。

目的　
　何のために作られたパッケージか、このパッケージを使うメリットは何であるかを記述する。

パッケージの設計方針
　コンポーネントを利用するに当たりコンポーネントユーザが知っておくとためになるようなコンポーネントの中に採用しているアーキテクチャについて解説する。

パッケージの適応範囲
　どのようなプラットフォームで利用可能か、利用者が不適切なプラットフォームで利用しないように詳しく解説する。

パッケージの使用条件
　パッケージ利用の前提となる条件や制約事項。たとえば、複数スレッドから共有利用できないなどといった制約があれば記述する。

変更点と問題点
　現バージョンの問題点（分かっているバグ情報）
　前バージョンからの変更点

クラス図
　コンポーネント利用者が知っておくべきクラスをクラス図などを使って解説する。

主なクラス名と概説
　コンポーネント利用者が知っておくべきクラスの名前とその役割を解説する。

コンポーネントリファレンス
　それぞれのコンポーネントを解説するコンポーネントリファレンスがここに添付される。

サンプルソースまたはチュートリアル
　サンプルソースが添付される。フレームワークのように大きなパッケージの場合は、チュートリアルを付ける。


提供方法

チェックリスト

パッケージがフレームワークのような大きな単位である場合にはチュートリアルが含まれいるか。
　気の利いた題材を基に、フレームワークの使い方を手順的に解説する。これによって、フレームワークのユーザがフレームワーク内部に隠されているコンポーネント同士の関連を理解できるようにしなければならない。

パッケージ利用者に不必要な保守情報が入っていないか。
　パッケージ利用解説書はパッケージを利用する人向けのドキュメントであるため、保守情報を載せてはならない。

３４．２　コンポーネントリファレンス

対象ワークショップ

記載項目

説明
　何のために、どんなところが便利か、どのように使われるのか、などを解説したもの。

コンポーネントの利用方法
　継承可能か不可能かなどクラスの使い方について解説

クラス図
　コンポーネントが複数のクラスで構成される場合、コンポーネントユーザが理解しておかなければならないクラスやインタフェースの構成をクラス図で示す。

コンポーネントの使用条件
　コンポーネント利用の前提となる条件や制約事項。たとえば「マルチスレッドからの利用ができない」などといった制約を記述する。

属性の解説
　コンポーネントの属性は原則的には公開するべきではない。だだし、下記のような場合については、属性を公開することもある。

• 言語機能を使って定数の宣言を公開された属性として定義している場合
• 内部で使用するコンポーネント製品の制約上、属性を公開しておかなければならないもの

　このような属性のうち、ユーザが知っておくべき属性があるならば、ここでその解説を行う。


メソッドの解説
　メソッドの解説はクラスの解説の中に記述される。メソッドには公開メソッドと私的メソッドがあり、私的メソッドはクラスの要求を実現するための実装のみを担当するメソッドなので、その名前はクラスの外から隠される。それに比べ公開メソッドはクラスの要求そのものをメソッド名として持ち、その名前は公開しなければならない。メソッドの解説には、以下のような項目が必要とされる。

• メソッドの名前　
• メソッドのパラメータと戻り値の解説　
• 機能解説（利用者へ提供する機能の説明や例外処理について）　
• 事前条件の解説
  メソッドを実行する際に知っておくべき重要な事前条件。たとえば、「」
• 使用条件の解説
  メソッドを実行する際に知っておくべき重要な使用条件があれば記述する。たとえば、「戻りのVectorは本メソッドを再度呼んだときに値が保証されなくなる」などといった情報。
• 継承によるオーバーライド可能か不可能かの説明　
• 使用例

コンポーネントの利用例（サンプルソース）

チェックリスト

メソッド利用のための事前条件が正しく記述されているか。
　常識の範囲で理解できることは書かない。たとえば、readメソッドの事前条件としてopenメソッドを呼び出しておくことといったようなことは書くべきではない。ただし、ユーザにとって何が常識の範囲かは、コンポーネントがターゲットとするユーザによって判断すること。

オブジェクトレイアウトカードからクラスリフアレンスにドキュメントを書き写す際に、クラスの仕様変更点や追加点について反映されているか。

実際に動作可能な使用例が記載されているか。(サンプルにバグがないか)