作って遊ぼうJava(5) コメントとドキュメント、javadoc

Javaのプログラムをどのように記述するかは、Java Code Convention というガイド（ただし英文）にまとめられています。読みやすいプログラムを書くためには、このガイドに従ったほうがいいと思います。コメントについてもガイドに規定されていて、主に以下のような内容です。
(1) ブロック コメント (block comments)
　/*
　 * ソースファイル、メソッド、データ構造、アルゴリズムなどに関するコメント。
　 * ブロック コメントはファイルの先頭や各メソッドの前に書かなければならない。
　 * メソッドの中でのブロック コメントはコードと同じレベルに字下げしなければならない。
　 /
(2) １行コメント (single-line comments)
　/１行コメントもコードと同じレベルに字下げする。１行コメントの前に空行を置く。 /
(3) 後続コメント (trailing comments)
　a = b + c; 　　　　　　/後続コメントはJavaの文から十分に離す。 */
(4) 行末コメント (end-of-line comments)
　// 通常は連続したコメントには使わないが、コードの一部をコメントにするときは構わない。
(5) ドキュメント コメント (documentation comments)
　/** １行のドキュメント コメント。 */
　/**
　 * １行以上のドキュメント コメント。
　 * ドキュメント コメントは javadoc コマンドによってドキュメント化される。
　 */
この最後のドキュメント コメントをきちんと書けば javadoc コマンドによって立派なHTML形式のドキュメントに変換してくれます。今回、このブログのためにJavaでのプログラミングを始めて、最も恩恵を感じたところです。Small Basicでプログラミングしていたときは、自分で作ったプログラムの作りを確認したい場合、大抵、ソースファイルをプリントアウトして、ペンで色を付けたりしていました。javadoc のドキュメントがあれば、クラスやメソッドなど簡単に確認できます。
javadoc はjdkに含まれるツールですが、何の指定をしなくても日本語のドキュメントを作成してくれました。そのため、Small Basicでは英語のコメントを書いていたのですが、Javaではコメントを日本語にすることにしました。ただオプションとして -charset “shift_jis” のようにコード系を指定する、とHTMLにコード系が記されるので文字化けが起きにくくなります。
Eclipseからjavadocを起動するには[プロジェクト][Javadoc の生成…]で「Javadocコマンド」のありか（jdkをダウンロードしたところ）を指定し、「Javadocが生成される型の選択」でドキュメント化したいクラスを選び、[次へ(N) >]で「文書タイトル」を指定し、[次へ(N) >]で「追加の Javadoc オプション」を指定し、[終了]を押すと、ドキュメントが作成されます。

【図5 EclipseでのJavadoc オプションの指定（シフトJISの場合）】
（つづく）