いまさら聞けない「Javadoc」と「アノテーション」入門：【改訂版】Eclipseではじめるプログラミング（22）（1/4 ページ）

これからプログラミングを学習したい方、Javaは難しそうでとっつきづらいという方のためのJavaプログラミング超入門連載です。最新のEclipseとJava 6を使い大幅に情報量を増やした、連載「Eclipseではじめるプログラミング」の改訂版となります

[小山博史，株式会社ガリレオ]

注釈とコメントで開発しやすくしよう

　開発者がソースコードにコメントを自由に記述すると、統一性がなくなり、同じ内容をさまざまな表現で書いてしまいます。これを防ぎ、重要な情報について統一的な表現で記述したいときは、「アノテーション（annotation、注釈）」を使うことを検討してみましょう。

　Javaではアノテーションをプログラムのソースコードへプログラムのメタデータとして記述できます。また、プログラムにアノテーションを埋め込むことにより、単純なミスを防ぐこともできます。さらに、アノテーションを利用する便利なライブラリもあります。

　今回は、実際の開発現場で必須の知識であるアノテーションと、それに関連して「Javadoc」（Javaドキュメンテーション）コメントについても説明します。

　EclipseでJavaプログラミングを始める準備がまだの方は、連載第1回の「Eclipse 3.4で超簡単Javaプログラミング基礎入門」で準備をしておいてください。

Java開発に便利な「Javadoc」を使いこなそう

　アノテーションの前にJavadocコメントについて理解しておくと、より理解が深まります。簡単にですが、先に説明しておきます。

「Javadoc」とは

　Javaでは、「Javadoc」と言われるコメントを記述できます。これは、プログラムについて説明するドキュメントをソースコードに埋め込むためのものです。

　プログラムについての説明をソースコードに埋め込むことができないと、プログラムの説明文は別ファイルで管理することになります。すると、ソースコード用ファイルと説明用ファイルの両方を管理する必要が出てきます。この管理方式を採用すると、開発者が忙しかったり軽微な修正を行うときに、「ついついドキュメントの更新を忘れてしまう」といったことが起きます。その結果、説明と動作が一致しないことが発生して問題となります。

　Javadocを上手に使うと、ソースコードの修正時にドキュメントの修正もできるため、こういったことが発生しにくくなります。

　Javadocは大変便利で、クラスの概要やメソッドの概要を記述しておくと、その情報からHTML形式のドキュメントファイルを生成してくれます。Java Platform SEのAPIリファレンスは実際に、この機能を使って生成しています。

概要 (Java Platform SE 6) via kwout

Eclipseで「Javadoc」を生成

　試しに、プログラムを作成してみましょう。これまで使用していたプロジェクトとは別のSample22プロジェクトを新規作成します。

1. ［ファイル］→［新規プロジェクト］→［Javaプロジェクト］を指定
2. ［プロジェクト名］に「Sample22」を入力して［終了］をクリック
3. 作成された「Sample22」をマウスの右ボタンでクリックしてメニューから［プロパティー］を指定
4. プロパティーダイアログでリソースのうち［テキスト・ファイル・エンコード］について［その他］を選んで［UTF-8］を指定

　準備ができたら、そこへsample22.app1パッケージを追加してから「JavaDocSample」クラスを作成します。Javadocコメントを記述するには、次のようにします。これでJavadocコメントのひな型が挿入されます。「/**」と「*/」で囲まれているものがJavadocコメントです。

1. エディタ上でclassという文字列にマウスカーソルを重ねてから、右クリック
2. 表示されたメニューから［ソース］→［要素コメントの生成］を指定

　最初は「作成者」を意味する「@author」だけが記述されているので、ここへ次のように、説明と「バージョン」を意味する「@version」を追加します。この「@author」や「@version」といった文字列はJavadocコメントの中で特別な意味を持つタグです。この他にも、いくつかのタグがあります。

package sample22.app1;
 
/**
 * Javaドキュメンテーションコメント
 * @author koyama
 * @version 1.0
 */
public class JavaDocSample {
}

EclipseでJavadocからHTMLファイルを生成

　次の手順でJavadocコメントからHTMLファイルが生成できます。［パッケージ・エクスプローラー］でSample22を選択しておいてください。

1. Eclipseのメニューから［プロジェクト］→［Javadocの生成］を指定して、Javadoc生成ウィザードを起動
2. Javadocコマンドには、「C:\Program Files\Java\jdk1.6.0_11\bin\javadoc.exe」を指定。バージョンアップしてある場合は、jdk1.6.0_11の部分を使用しているバージョンに合わせて指定
3. ［Javadocが生成される型の選択］で「Sample22」をチェックしてから［次へ］をクリック
4. ［文書タイトル］をチェックして「サンプル」と入力後［次へ］をクリック
5. ［VMオプション］へ「-encoding UTF-8 -charset UTF-8」を指定して［終了］をクリック
6. Javadocロケーションの更新を確認するダイアログが表示されるので、すべて［はい］をクリック

　生成したJavadocコメントのHTMLファイルはEclipse上で参照できます。［パッケージ・エクスプローラー］上で該当クラスを指定した状態で、Eclipseのメニューの［ナビゲート］→［外部Javadocを開く］をクリックします。

　Windowsファイアウォールの警告が出る場合は、［ブロックを解除する］をクリックします。すると、Webブラウザが起動して、Javadocを読むことができます。

Javadocのような「メタデータ」を活用する動き

　このようにJavaでは、ソースコードへドキュメンテーションコメントを埋め込めます。ドキュメンテーションコメントのようなソースコードに関する情報は、ソースコードに対する「メタデータ」といえます。つまり、Javaではソースコードにプログラムだけでなく、プログラムに関するメタデータを埋め込むことができるのです。

　この便利な機能に目を付けた開発者が、特別なコメントをメタデータとしてソースコードへ埋め込むことを始めました。例えば、「XDoclet: Attribute-Oriented Programming - Welcome」で公開されている「XDoclet」などがあります。

＠IT：現場に活かすJakarta Project 第3回 via kwout

　XDocletが注目を浴びたころは、Javaにはアノテーションはありませんでしたが、現在のJavaでは、このメタデータをより利用しやすくするための仕組みとしてアノテーションが導入されています。

　作成したプログラムのリファレンスドキュメントを作成するにはJavadocコメントを使って、HTMLファイルを生成すればいいのですが、アノテーションを使うと、もっといろいろなことができるようになります。

ただの「注釈」ではない！ 「アノテーション」とは

　アノテーションとは、「注釈」という意味です。Javadocコメントは開発者に対してプログラムがどういうものかを説明するために使いましたが、これと同様に、コンパイラや実行環境に対してプログラムがどういうものかを伝えたいことがあります。

　後述する具体的な例を見れば分かりますが、Javaではアノテーションをプログラムに記述することにより、コンパイラで出力される警告メッセージを抑制したり、実行環境によってプログラムの動作を変更したりできます。

　Javaではアノテーションを記述するためにはアノテーション型を使います。これにより、ソースコードへ記述が必要な情報について、項目チェックができるようになります。つまり、開発者が必要な情報を正しく書けるようになります。

　また、プログラムが解釈できる形でメタデータが埋め込まれるため、コンパイラや実行環境が、それを解釈して何らかの処理を行うようになります。

アノテーションの必要性

　なぜアノテーションのようなものが必要なのでしょうか。個人が作成するような小規模プログラムを作成しているときは、1人で全体を見通せますが、大規模なプログラム開発においては、複数の開発者全員が全体の概要を理解しながら、同じコーディングスタイルで開発する必要があります。それぞれが自分の好きなスタイルで開発をすると、コード全体の統一感がなくなり、複数の開発者でコードメンテナンスをする際に効率が悪くなるからです。

　このとき、「コーディングスタイルについてルールを決めて、そのルールに従ったコードを記述する」という方法がありますが、文書や口頭による申し合わせでは徹底できないことがあります。これを徹底させるためにアノテーションは利用できます。

スレッドセーフかどうかや、依存設定の情報など

　例えば、ドキュメント情報として必要なものとしては、著作権情報、プログラムの作成者、作成日時、更新日時、バージョンといったものが考えられます。他には、マルチスレッドプログラミングで使用されることを考慮したスレッドセーフなプログラムなのかを分かるようにしたいということもあるでしょうし、プログラムが依存している設定ファイルの情報もソースコードに記載したいということもあるでしょう。

　こういった情報を統一的にコードへ埋め込みたい場合に、「アノテーション」という形でソースコードへ注釈を付ければ、解決できます。

テストなど開発に必要な情報も

　アノテーションがプログラムのメタデータである点に注目すると、開発者用のドキュメント情報をソースコードへ記述するために使うだけではなく、「プログラムの開発環境や実行環境にとって有用な情報を埋め込む」といった用途で使うこともできます。

　例えば、Javaプログラムの単体テスト用ライブラリである「JUnit 4」では、テスト用プログラムにあるアノテーションが付いたメソッドをテスト用メソッドとして実行できます。

　説明だけではイメージしにくく、難しそうな気がするかもしれませんが、実際に使ってみると意外と簡単だということが分かるはずです。

　次ページでは、よく使う3つの標準アノテーション型について解説します。