渋い本です。まさかJavadocだけで一冊の本があるとは。
Javadocというのは、Javaのソースコードでクラスやメソッドや引数や戻り値について決められた書式でコメントをつけていくと、ポンと自動的にマニュアルをHTMLドキュメントで作ってくれるプログラムです。Javaのコンパイラーに最初からついていますね。
ひとりでプログラムを書いているとJavadocなんて無視しちゃうんですけど、そうすると自分で書いたコードも何をやっているのか思い出すのに非常に時間がかかりますよね。ましてや人に使ってもらうためのコードだったらなおさらです。この本はどのようにコメントをつけていけば、役に立つドキュメントが作れるのかを懇切丁寧に説明しています。
コーディングの生産性を上げるためにはカプセル化(encapsulation)というのが欠かせません。カプセル化というのは、内部のデータ操作や計算処理を外からアクセスできなくして、クラスをブラック・ボックスにすることです。必要な機能を実現するために必要最小限のメソッドだけをパブリックにします。Javaでソースコードを書くとき、プログラムがインスタンス変数に直接アクセスできるようにしては絶対にいけません。どんな場合でもオブジェクトのデータを扱う場合は、そのオブジェクトのメソッドを通して「のみ」にしないといけません。
なぜそんなことが必要なのでしょうか。たとえばあるプロジェクトでは1000個の関数(メソッド)が必要だとしましょう。ある処理の途中でバグが発生して、データがおかしくなってしまったとします。そのデータがどの関数からもアクセス可能だったら、1000個のメソッドを調べていかなければいけません。ところが10個のメソッドを持つ100個のクラスで設計していたら、おかしくなったデータを持つクラスのなかの10個のメソッドだけを調べればいいでしょう。よって、クラスを作るときに、内部のデータには絶対に直接触れるようにしてはいけないのです。またそうすることによって、クラス内部のデータ構造や計算処理を変更しても、外からは最小限のメソッドだけを通してアクセスしていますから、他のクラスには影響しなくなります。
さて、うまくカプセル化されたクラスを作ったとして、そのクラスを他の人(自分も含む)がいつでもすぐに使えるようにするためにいいドキュメントが必要なのです。基本的にクラスを作るとき、そのクラスの使い方が中身を見なければわからなかったら「負け」なのです。カプセル化して自然言語で必要かつ十分な説明を書いて、はじめて完成されたクラスになります。
それではみなさんもこの本を読んで「ちゃんとした」ドキュメントを作れるようになりましょう。僕も心がけます。もう二度とコメントが全くないソースコードなんか書いたりしません。(笑)