『エンジニアのためのJavadoc再入門講座』を読んだ。本書は丸々一冊を費やして、Javadocについて書いている。つまり、コメントについて書いている。けれど、いくらうまくコメントしても、使いにくいAPIが使いやすくなったりはしない。次のように釘を刺している。
ドキュメンテーションコメントが書きづらい、と感じたなら、まずそのクラスやメソッドの設計のまずさを疑ってみましょう。『リーダブルコード』を思い出す。まずいコードにいくらコメントをつけたって読みやすくはならない。それと同じことだと思う。そういうコードに悪戦苦闘しながら付けたコメントは、得ててゴチャゴチャと読みにくいものになってしまいがち。
いわゆるロジカル・ライティングとも通底している。コードであれ自然言語であれ、対象をうまく構造化しないと、それについて簡潔に書くことができない。
一方で、構造化するために書くことが大きな助けになるから、 大抵の場合、書く前には書いた後ほどうまく構造化できない。書いても書いても、これで完璧、とは中々思えない。むしろ書けば書くほど、手直ししたい箇所が増えてくる。
だから、コードならリファクタリング、自然言語なら推敲というプロセスがあるのだけれど、コードの場合、リファクタリングしているうちにコメントのメンテナンスをおざなりにしてしまいがち。テストも書かないといけないし、なかなかコメントまで手が回らない。
でも、本書にある通り、コードとテスト読んでも分からないことがあるわけで、それはキチンと書いて、使う人に伝わるようにしたい。もちろん、合わせて、なるべく早い段階でまともな設計をして、伝えることをハッキリさせる必要もある。
その点、本書は『契約による設計』の観点から、ハッキリさせておくべきことがリストになっているところがありがたい。この観点は、例外設計における大罪で読んだことはあったけれど、今回、例外 (@Exception) に限らず、引数 (@param)、返値 (@return)とセットで考えられて、少し理解が進んだように思う。
あとはちゃんと使わないと。