TOPシステム開発> 前回までのおさらい「Javadocが果たす役割とは」




Javadoc
Javadocから考える開発ドキュメンテーション

第3回:「どのように検証するのか」をJavadocで実現する

著者:ウルシステムズ  足立 祐一   2007/9/4
1   2  3  次のページ
前回までのおさらい「Javadocが果たす役割とは」

   Javadocはソースコードとドキュメンテーションコメントからリファレンスドキュメントを作成するツールです。ソースコード中のクラス宣言やメソッド宣言と、それらの内容についての説明が書かれたドキュメンテーションコメントを、Javadocが解析してHTML形式のリファレンスドキュメントを作成します。

   ソースコードを書く開発者は通常、クラスやメソッドを設計・開発しながら、設計について「なぜそうなっているのか」といった説明や利用の仕方をドキュメンテーションコメントとして残すことができます。つまり、Javadocで作成したリファレンスドキュメントをみれば、クラスやメソッドの設計や利用について、開発者の意図したところが理解できるのです。

   しかし、通常のJavadocで作成されたリファレンスドキュメントだけだと、ソースコードをどういう意図で作ったのかはわかりますが、そのソースコードが正しいかということまではわかりません。

   「ソースコードが正しいか」を確認する視点には2つあります。1つ目は、そのコードで「どんなシステムを作るのか」という視点、2つ目は正しく実現されていることを「どのように検証するのか」です。

   1つ目の「どんなシステムを作るのか」については、「第2回:『どんなシステムを作るのか』をJavadocで表現する」を通じてリファレンスドキュメントで表現する方法を紹介しました。この方法ではJavadocを拡張し、仕様書へのリンクを付けることで、リファレンスドキュメントのリンクを辿ってクラスやメソッドが実現しようとする機能が妥当なものであるかどうかを仕様書で確認できるようにしています。

   今回は、2つ目の視点である「どのように検証するのか」をJavadocで実現する方法について解説します。

今回の内容

   下記の3点について解説します。

  • JavadocをTaglet機能で拡張し、リファレンスドキュメントのクラスやメソッドと対応するテストクラスやテストメソッドをリンクさせる
  • Taglet機能で拡張したJavadocをビルドプロセスに組み込む方法
  • これらのJavadocの拡張に加え、いくつかのシステムを利用することで、継続的な開発を可能にする環境を提案

表1:今回解説する内容


ソースコードを「どのように検証するのか」

   ソースコードが正しく実装されているかを検証する手段に「テスト」があります。システム開発では粒度や観点の違うテストを組み合わせて行いますが、それらの中でも特に重要なのは「ユニットテスト」です。

   ユニットテストは「ソースコードのクラスやメソッドが正しい実装となっているかを確認する」という観点で行うので、ここをしっかり押さえておくことで、ソースコードの正しさを確認することができます。逆にいえば、この部分をないがしろにした場合、ソースコードの正しさは確認できないことになるのです。

   そこで、今回はJavadocを拡張して、テストの中でベースとなるユニットテストに焦点をあてた「テストタグ」を定義します。テストタグは、Javadocが作成するリファレンスドキュメントにテストへのリンクを付けるためのものです。

   通常、ソースコードとテストの記述は別々に管理されており、どのクラスやメソッドがどのテストにあたるのかがわかりません。しかしこのテストタグをソースコードのドキュメンテーションコメントに入れておくことで、Javadocによってクラスやメソッドに対応するテストへのリンクを自動的に付けられるようになります。

   今回使用するソースコードのサンプルは以下のURLからダウンロードできます。

ソースコードサンプル
ZIPファイル Javadoc_03.zip (ZIPファイル/14.5KB)

1   2  3  次のページ


ウルシステムズ株式会社 足立 祐一
著者プロフィール
ウルシステムズ株式会社  足立 祐一
コンサルタント
Javaを中心にアーキテクチャ設計〜アプリケーション開発に従事し、製造業界、金融業界のSIerを経て現職。新しい技術、古い技術を駆使し、お客様の課題をITによって解決できるシステムを提供すべく、日々奮闘中。


この記事の評価をお聞かせください
ボタンをクリックしますとウインドウが開きます。

INDEX
第3回:「どのように検証するのか」をJavadocで実現する
前回までのおさらい「Javadocが果たす役割とは」
  テストタグを作成する
  継続的な開発環境構築に向けて(Javadocだけでは解決できないこと)
Javadocから考える開発ドキュメンテーション
第1回 Javadoc、どのくらい活用していますか?
第2回 「どんなシステムを作るのか」をJavadocで表現する
第3回 「どのように検証するのか」をJavadocで実現する