読んだ

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

こんな感じインターフェイスがあった場合、

List<Cuntomer> getCustomers(String name)

引数の名前をキーにした検索結果の顧客のListを返すんだなってのは分かるわけですが、ここでEclipseかなんかで、Javadoc用コメントを自動生成すると

@param name
@return

は自動的に作られて、この際、

@param name 顧客名
@return　顧客のList

とか、書くってのは全く意味ないじゃないってことでね。こういうの書く人は、このタグがJavadocという機構で使用されるためのものであるという認識はないんだろう。そんなことは十分ありますよ。ひどいコメントたくさん見てましたから最近は。

ここでいうと、パラメータの閾値はどうなんだとか、一件も戻りがなかったときに何が返却されるのか？(null or 空のリスト or 例外発生？)とかをこのメソッドのAPI仕様として書くという態度がドキュメンテーションコメント(仕様としてのコメント)であるということが滔々と語られていくのであります。

契約による設計とかにも触れつつJavadocとの絡みで、どのようにコードは書かれるべきで、それについてどのようなドキュメンテーションコメントが適切なのかということが語られる。初心者はクラス設計など考えずに、とにかくこの処理を実現できるようにとワーって書いちゃうことってあると思うのだけれども、Javaってクラスの呪縛から逃れることは絶対にできないのであって、必ず責務を担っちゃうんであって、その辺を考えつつ、他者を想定してこのAPIはどう思われるだろう？このクラスってどうだろう？このインターフェイスでうまく抽象化できているかな？拡張性はどうかな？ってことを意識していくことがオブジェクト指向とかへの理解につながっていくんだろうと思います。

テクニカル面よりも、どのようにどこにどう書くのかといった原理原則に多くが割かれてはいるんですが、もちろんJavadocの使用法(タグとか)についてもきちんと説明されています。ただこうした部分って言うのは、読んで理解してもだめなんで、javadocコマンドなりmavenなりを動かして参照していくことになるんだと思います。そうですね。

詳細設計書ってのは、本当に、本当に、そのまま、コードにしちゃだめです。その詳細設計書が、それ系の詳細設計書だったらば。単なる仕様を上からコーディングしちゃいましたよ的なJavaコードの悲しさってあるじゃないですか？本当にあるんですよ。動いてるんですよ。ギャグじゃなくて。ひどいコードを書かなくて済むように、少しでもなくなるように、ドキュメンテーションコメントを考えていくだけでもJavaの設計センスやコーディングセンスは飛躍すると思っています。きちんと書きましょう。仕様としての、コメント。ヒトヨンデ、ドキュメンテーションコメント！

Effective Java 第2版 (The Java Series)

第二版を詳細に読んでるんですが、この辺にもつながる話はあると思います。しかしこの本も本当にいい本だと思います。第一版の時は、まだよくわからなかったけれど、今は少しは分かるようになってきているのかと思います。いいです。

Javaの格言―より良いオブジェクト設計のためのパターンと定石

あとこれも再読しましたが、こちらもいい本ですね。クラスローダのこととか例外の部分とかずいぶん勉強になります。会社にあったのにいくら見つけてもないので、自費で購入しました。また読みます。クラスローダって面白い。