複数人での開発を円滑にする「Javadoc」について紹介

TOP
コラム
複数人での開発を円滑にする「Java

はじめに

Javaは、サン・マイクロシステムズから1990年代半ばにリリースされたプログラミング言語で、サン・マイクロシステムズがOracle社に吸収合併された関係で現在の開発・管理はOracle社となっています。JavaはJVM(Java Virtual Machine)と呼ばれる実行環境さえインストールすればMac、Linux、WindowsといったOSに依存せずに利用でき、フレームワークやライブラリが充実していることもあり、幅広いシステムで利用されています。コンパイラ言語であるため実行速度が早く、セキュリティが堅牢という点もJavaのメリットです。

代表的な用途としては、Webサイト、Webアプリ、業務システム、金融システム、組み込み系、IoT等が挙げられます。また、スマートフォンのAndroidで利用されるプログラミング言語「Kotlin」はJavaをベースに開発されており、2022年時点でJavaとの互換性こそないものの、JVM上で動作する仕組みとなっています。

その一方で、Javaは難しい言語として挙げられることが多く、習得するまでの学習に時間を要するという面があります。その原因となっているのが「オブジェクト指向」という概念で、これはそのままJavaの大きな特徴の一つとなっています。しかし「オブジェクト指向」という概念を採用した言語はPHP、 Ruby、JavaScript、C++等たくさんあり、それぞれ近年のシステム開発では欠かせない存在となっています。そのため、Javaを習得することで、同じオブジェクト指向の言語を習得しなければいけない状況になったとしても、学習時間を短縮できる可能性が出てきます。

この記事では、そんなJavaでの説明書き(コメント)に関する機能を紹介します。コメントは、記述したプログラムに対して行うもので、人間が見た時にどの部分の記述なのかを一目でわかるようにする役目を持っています。コメントはJavaにかかわらず多くの言語で可能な機能であり、問題集で例えると、解答に対する解説がコメントに該当すると言えます。今回は、Javaの基本的で簡素なコメント方法を紹介した上で、「Javadoc」を使った説明書のようなドキュメントを作成する方法を紹介していきます。Javaでのコメントを見やすくしたいと思っている方、これからJavaを学習しようとしている方はぜひご覧ください。

Javaでのコメント記述方法をおさらい

様々なプログラミング言語を利用しているプログラマーの方は、使う言語が変わるごとに、コメントアウトするための記号がどれであったか迷ってしまうことがないでしょうか。それだけ、言語によってコメントアウトの方法は様々です。なお「コメントアウト」とは、記述した内容がプログラムとして実行されないように除外し、単なるコメントとして残すことを意味しています。最初からコメントを記述する意図で利用する場合においてあまりコメントアウトとは言いませんが、実際やることは変わらないので、今回の記事において「コメントアウト=コメントの記述」と考えてもらって特に問題ないです。コンパイルしてプログラムの成否を確かめたい時に一部記述を除外する場合、記述内容に対して人間の言語で説明を加えたい場合等にコメントアウトを利用します。

Javaでコメントする場合は、「//」を利用し、「// コメントを記述する。」というように「//」の後に半角スペースを入れ、その後にコメントしたい内容を続けます。しかしこの方法では、「//」が記述された1行しかコメントアウトしてくれません。行ごとに先頭に「//」を付ければ複数行をコメントアウトできますが、とても面倒です。そのため、複数行をまとめてコメントアウトしたい場合は対象の行を「/*」と「*/」で囲みます。記述例を以下に紹介します。

/*
複数行をコメントアウトしたい1
複数行をコメントアウトしたい2
複数行をコメントアウトしたい3
*/

なお、1行だけをコメントアウトする「//」の場合は、末尾を「//」で囲む必要はありません。以上を踏まえて、以下の基本的なJavaのプログラムを実行してみましょう。

public class Hello {
    public static void main(String[ ] args) {
 /*
ディスプレイに表示するためのメソッド
これを実行するとHello Javaが表示されます
*/
        System.out.println("Hello Java");
    }
}

通常、上記のような簡素な記述に対してコメントをすることはありませんが、プログラミングが長文となればなるほど、可読性を高めるためにもコメントの記述は重要になってきます。なお、これを実行すると実際に「Hello Java」とだけ表示されるので、コメントアウトが効いていることが確認できます。続いて今回のメインとなるJavadocについて紹介していきます。

Javadocとは？

Javadocも、プログラム内に記述すること、コメントアウトした部分に関してはプログラムとして実行されないという点は同じです。しかしながらJavadocのルールに沿ってコメントを残し、かつJavadocを生成した場合、その内容が記述されたドキュメントがHTML形式で作成されます。また「@」から始まる「Javadocタグ」を利用すると、フォーマット化された見やすいドキュメントの作成が可能となります。Javaでは、プログラミングで利用できるパッケージやクラス、メソッドについての仕様がまとめてWeb上で確認できる「APIリファレンス」というサイトが用意されています。APIリファレンスでは、一定のフォーマットに沿って概要や利用方法等が記載されていますが、Javadocでもそれに似た形式のドキュメントが作成できます。まだ見たことがない方は、「java api リファレンス」等で検索するとJavaのバージョンごとのAPIリファレンスが見れるので、ぜひ確認してみてください。

Javadocのルールに沿った記述は以下となります。

public class Hello {
    public static void main(String[ ] args) {
/**
* これがJavadocに沿った
* コメント挿入方法です
*/
        System.out.println("Hello Java");
    }
}

通常のコメント時と似ていますが、コメントの始まりは「/**」となり、各行の先頭にも「*」を入力する必要があり、最後は「*/」で閉じることとなります。また、コメントはHTMLとして解釈されるため、プログラム内でエンターキーを使って改行したとしても、生成されるドキュメントでは改行が反映されません。改行を反映させたい場合は、HTMLの改行タグである
を挿入しましょう。通常のコメントと混同してしまうことはあるかもしれませんが、ルール自体は特に難しくないことがわかっていただけたことでしょう。なおJavadocのコメントは、次に紹介するタグと合わせ、説明文の箇所とタグセクションの箇所で構成されます。

Javadocのタグについて

Javadocはあらかじめ定められた様々なタグを利用することで、ドキュメントを見やすく構成してくれます。タグはコメント内で複数利用することができ、「@」で指定する必要があるため、「@」は特殊文字として扱われます。また、タグによっては同じコメントの中で複数回使用できないものがあること、タグの後に説明文が入っていても無視されることも覚えておきましょう。

ダグは種類がたくさんありますが、使われることの多いものを一部紹介しておきます。プログラムの著者を記述する「@author」、初めて作成したバージョンを記述する「@since」、現在のバージョンを記述する「@version」、引数(パラメーター)を記述する「@param」、戻り値を記述する「@return」、例外を記述する「@throws(@exception)」、定数値を記述する「@value」等が挙げられます。これらのタグにはそれぞれ入力規則、ルールがあります。例えば「@author」は、「,」+スペースで複数の記述が可能、「@param」は、プログラムのメソッドに記述されている引数名と異なる内容が「@paramの後に記述されている場合、Javadocを生成しようとすると警告が表示される等です。基本的には、プログラムの内容と矛盾していなければ問題はありません。タグを使った記述のイメージは以下のようになります。

/**
 *  Javadocのコメントは

 *  このように記述します。
 *  @version 1.0
 *  @author JavadocUser
 */

Javadocを生成する方法

続いてJavadocのHTMLドキュメントを生成する方法について紹介していきます。ここでは、コマンドで生成する方法と、Javaでよく利用される統合開発環境(IDE)「Eclipse(エクリプス)」での生成方法の2通りを紹介します。

コマンドを実行した場合

Javaでのコメント記述方法で取り扱った「Hello」クラスのHTMLドキュメントを生成する場合は「javadoc -d doc Hello.java」というコマンドを実行します。なお「doc」の部分は「java」ディレクトリ配下の構成によって異なるので、みなさんの環境に適したディレクトリを指定しましょう。このコマンドを実行することで、「doc」ディレクトリ配下に「index.html」が作成されるので、ダブルクリック等でブラウザで開いてみましょう。ブラウザでは「/**」「 */」で囲まれた部分の内容がAPIリファレンスのようなフォーマットに整形された状態で表示されることとなります。

Eclipseを利用した場合

Eclipseの場合は、初めに上部の「ファイル」から「インポート」をクリックしてください。続いて「Java」ディレクトリ内の「Javadoc」を選択して「次へ」をクリックします。「Javadocコマンド」欄にはjavadoc.exeの設置場所が表示されていると思いますが、もし表示されていない場合は「構成」をクリックして指定しましょう。「Javadocが生成される型の選択」欄では、ドキュメントを生成したい対象のファイルを選択します。今回の場合は「Hello」を選択することとなります。

次に「次の可視性を持つメンバーのJavadocを作成」の部分は特に変更しなくても問題ありませんが、ドキュメントに含めたい範囲を選択する箇所となります。例えばPrivateメソッドを出力したくない場合は「Public」を選択しましょう。「宛先」ではドキュメントの出力先を指定し、「次へ」をクリックします。基本オプションやタグの記述に関するチェック項目等が表示されますが、そのまま「次へ」で進み、次の画面で「完了」をクリックしましょう。なお、Eclipseの文字コード設定が「UTF-8」となっていることで出力に失敗する場合があります。この場合は、「完了」ボタンを押す画面内にある「追加のJavadocオプション」という部分で、「-encoding UTF-8」「-charset UTF-8」の二つを追加して「完了」をクリックしてみてください。

以上の作業が完了したら、指定した場所に「index.html」が作成されているか確認してみましょう。作成されていたら、「index.html」を選択した状態で右クリックして「次で開く」「Webブラウザー」を選択すると、ブラウザ上でドキュメントが表示されます。表示されたページにて、「パッケージ」＞「クラス概要」の中の「Hello」の順で進んでいくと、コメントした内容に沿った詳細情報が確認できます。

なお、Eclipseでコメントの記述も行う場合の豆知識を一つ紹介します。プログラム内のコメントしたいメソッド等にカーソルを合わせた状態で、Windowsの場合は「Alt + Shift + J」、Macの場合は「option + command + J」をキーボードで同時に押すことで、Javadocのルールに沿ったフォーマットが追加されるので入力の手間が省けて、誤りを防ぐこともできます。

まとめに

プログラム内に記載された通常のコメントだけであっても、開発者同士の引き継ぎでは十分事足りることでしょう。しかし今回紹介したJavadocを利用することで、より可読性の高いドキュメントが作成できるため、専門の開発者でなくても、生成されたドキュメントを見ることで概要が把握しやすくなります。JavaのAPIリファレンスのようにまとめられるため、プロジェクトによってはそのまま資料の一つとして利用することもできるのではないでしょうか。記述方法、生成方法については特に難しい部分がなく、専門的な知識が求められる部分も少ないですが、細かい記述ルールを忘れてしまった場合は、ぜひこの記事を見返していただけると幸いです。