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

前回までのおさらい「Javadocが果たす役割とは」

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

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

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

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

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

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

今回の内容

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

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

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

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

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

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

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

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