doxygenで何を書くのか？
doxygenには様々なコマンドが存在するが、今回は、ソースコードにソフトウェア詳細設計書を埋め込むという観点で、doxygenのコメントとして何を記述すればよいかということを考察する。
doxygenコメント作法・規約を定義するにあたり、ソフトウェアは以下のような構成をしていることとする。
- 機能ユニット（クラスやスレッド）ごとにファイルを作成する
- 各機能ユニットはソースファイルとヘッダファイルを一組として構成する
- ヘッダファイルには機能ユニット間のインタフェースを定義する
- ソースファイルには機能ユニットの実処理を実装する
ファイルヘッダ
ファイルヘッダとはファイルの先頭に記述するコメントのことである。ファイルヘッダには、そのファイル全般に関わる事項を記述する。
- ファイルヘッダに記述する事項
- 機能ユニットの概要
- 機能ユニットの機能・役割を一行で記述する。
- 注意事項
- 機能ユニットに関する注意事項があれば、箇条書きで記述する。
- 補足事項
- 機能ユニットに関する補足事項があれば、箇条書きで記述する。
- 参照情報
- 機能ユニットに関する参照情報を箇条書きで記述する。例えば、ソフトウェア・アーキテクチャ設計書の該当する章や図表の番号やタイトルなどを記述する。
- 変更履歴
- いつ、誰が、どのような変更を行ったのかを記述する。ファイル全体に関する変更はここに記述する。関数、クラス・構造体などの定義をファイルに追加、またはファイルから削除した場合はファイルヘッダへ記述する。関数内の処理の変更やクラス・構造体のメンバ変数の変更などは、後述するそれぞれのヘッダへ記述する。
- ファイルヘッダのフォーマット
/*---------------------------------------------------------------*/
/**
@file ファイル名
@brief 機能ユニットの概要
@attention 注意事項
@note 補足事項
@sa 参照情報
@date 変更履歴
*/
/*---------------------------------------------------------------*/ |
関数ヘッダ
関数ヘッダとは関数定義の前に記述するコメントのことである。関数ヘッダには、その関数に関わる事項を記述する。
- 関数ヘッダに記述する事項
- 関数の概要
- 関数の機能・役割を一行で記述する。
- 関数の詳細
- 関数の処理内容を箇条書きで記述する。
- 注意事項
- 関数に関する注意事項があれば箇条書きで記述する。
- 補足事項
- 関数に関する補足事項があれば箇条書きで記述する。例えば、関数が実行されるスレッドなど情報を記述する。
- 参照情報
- 関数に関する参照情報を箇条書きで記述する。例えば、ソフトウェア・アーキテクチャ設計書の該当する章や図表の番号やタイトルなどを記述する。シーケンス図の該当する箇所や処理内容を示したフローチャートなどがあれば記述する。
- 引数
- 戻り値
- 変更履歴
- いつ、誰が、どのような変更を行ったのかを記述する。
- 関数ヘッダのフォーマット
/*---------------------------------------------------------------*/
/**
@brief 関数の概要
@details 関数の詳細
-
関数の処理内容
@attention 注意事項
@note 補足事項
@sa 参照情報
@param
[in] 引数名 引数の説明
@param
[out] 引数名 引数の説明
@param
[in,out] 引数名 引数の説明
@return 戻り値の説明
@retval 戻り値名 戻り値の説明
@date 変更履歴
*/
/*---------------------------------------------------------------*/ |
クラス・構造体ヘッダ
クラス・構造体ヘッダとはクラス定義や構造体定義の前に記述するコメントのことである。クラス・構造体ヘッダには、そのクラス・構造体に関する事項を記述する。
- クラス・構造体ヘッダに記述する事項
- クラス・構造体の概要
- クラス・構造体の役割を一行で記述する。
- 注意事項
- クラス・構造体に関する注意事項があれば記述する。
- 補足事項
- クラス・構造体に関する補足事項があれば記述する。
- 参照情報
- クラス・構造体に関する参照情報を記述する。
- 変更履歴
- いつ、誰が、どのような変更を行ったのかを記述する。
- クラス・構造体ヘッダのフォーマット
/*---------------------------------------------------------------*/
/**
@brief クラス・構造体の概要
@attention 注意事項
@note 補足事項
@sa 参照情報
@date 変更履歴
*/
/*---------------------------------------------------------------*/ |
doxygenをどのように使うのか？
doxygenさえ導入すればソフトウェア開発の全てがうまくいくというものでない。doxygenはあくまでもソースコード内に記述したコメントからHTMLやRTF形式のドキュメントを生成するツールにすぎないため、コンポーネント図やシーケンス図などのUMLを用いてソフトウェア・アーキテクチャ設計を実施することは難しい。そこで、ここでは、doxygenをソフトウェア開発プロセスに効果的に導入する方法を考察する。
では、以下のようなアクティビティを含むソフトウェア・エンジニアリング・プロセスを例に説明する。
- ソフトウェア要求定義
- ソフトウェア・アーキテクチャ設計
- ソフトウェア詳細設計
- 実装
- 単体テスト
- ソフトウェア結合テスト
- ソフトウェア総合テスト
上記のプロセスのうち、ソフトウェア・アーキテクチャ設計から実装までのアクティビティは以下のようなタスクを含むとする。
ソフトウェア・アーキテクチャ設計のタスク
- 設計条件の確認
ソフトウェア要求定義で整理・体系化した要求や制約のうち、ソフトウェア・アーキテクチャを設計する上で重要なソフトウェア機能要求、非機能要求および制約条件をリストアップする。将来的に導入することが予想される要求や制約条件も可能な限りリストアップし、ソフトウェア・アーキテクチャを検討する上でのインプットとすることで、近い将来に大幅な見直しが必要となるリスクを低減する。
- ソフトウェア構成の設計
上記でリストアップした要求や制約条件とハードウェア構成などをもとに、ソフトウェアのレイヤと機能ユニットの分割方針を策定する。また、分割方針に従って、具体的に機能ユニットの分割を行い、各機能ユニットの役割を定義する。機能ユニットの分割は、クラスなどの静的構成とスレッドなどの動的構成の両方について行う。ソフトウェアの構成は、UML2.0のコンポーネント図を用いて表現する。また、実装方針として、ソフトウェア構成と結び付いたディレクトリやファイルの構成、プレフィックスの命名方針を策定する。
- ソフトウェア全体の振る舞いの設計
上記で分割した機能ユニット間の処理シーケンスを策定する。代表的なユースケースや特異なユースケースに対する処理シーケンスは必ず作成する。ソフトウェア全体の振る舞いは、UML2.0のシーケンス図を用いて表現する。
- インタフェースの設計
上記で策定した機能ユニット間の処理シーケンスをもとに、各機能ユニットのインタフェース仕様を策定する。
- ソフトウェア・アーキテクチャ設計書の作成
上記までの検討結果を整理・体系化して、ソフトウェア・アーキテクチャ設計書を作成し、リストアップした要求や制約条件に対するソフトウェア・アーキテクチャの妥当性を検証するという観点でレビューを実施する。
ソフトウェア詳細設計のタスク
- プログラムユニット分割
ソフトウェア・アーキテクチャ設計で策定した各機能ユニットのインタフェース仕様をソースコードに記述する。このとき、ファイルヘッダや関数ヘッダをdoxygenコメントで作成し、各機能ユニットや各インタフェースの機能を記述する。
次に、各機能ユニットのインタフェースに対して処理内容をリストアップして関数ヘッダに追記していき、それらを関数として分割する。各関数の仕様もソースコードに記述する。関数ヘッダをdoxygenコメントで作成し、各関数仕様の説明を記述する。
この時点では、インタフェース仕様や関数仕様のみを記述し、実処理は実装しない。
- プログラムユニット設計
上記で分割した各関数の処理内容を関数ヘッダに記述する。処理内容が複雑になる場合は別途フローチャートなどを作成し、関数ヘッダの参照情報に追記しておく。
- ソフトウェア詳細設計書の作成
ソースコードに記述したファイルヘッダや関数ヘッダなどのコメントからdoxygenを使ってドキュメントを生成し、ソフトウェア詳細設計書とする。また、レビューを実施する。
実装のタスク
- プログラムユニットの実装
ソースコードに記述したファイルヘッダや関数ヘッダなどのコメントに従って実処理を実装し、ソースコードを完成させる。また、doxygenコメントに記述した内容が正しく実装されているかという観点でレビューを実施する。
おわりに
今回は、doxygenを活用したソフトウェア開発プロセスの一例を示した。doxygenに限らず、現在では、様々なソフトウェア開発支援ツールやWebサービスなどをフリーかそれに近い低コストで利用できる環境が整っている。それらを上手く活用し、ソフトウェア開発の本来の目的である問題解決や価値創造に努めていきたい。
参考文献
- doxygenサイト（英文）
http://www.stack.nl/~dimitri/doxygen/index.html
- doxygen日本語サイト
http://www.doxygen.jp/
- 電八開発倶楽部
http://www.denshin8.jp/den8dev/doxygen.html
- サクラエディタ
http://sourceforge.net/p/sakura-editor/wiki/DoxygenComment/
