2015-12-16

これは Java Advent Calendar 2015 の 16 日目の記事です。

昨日は @yukung さんの Java で引数の null チェックで迷った話でした。明日は @mdstoy さんです。

ちなみに過去のJava アドベントカレンダーで書いたもの。

……2013年は書いてないのか。そうか。

前置き

3年前になりますが、コメントについては書いたことがあります。

http://irof.hateblo.jp/entry/20121104/p1

たまにスライド見返したりするのだけれど、今でもそれほど主張は変わらない感じです。

で、先に挙げた記事はインラインコメントがメインとなっていますので、今回はドキュメントコメントについて書いてみることにします。

Javadocと言えば

Javadocと言えばHTMLのあいつ。 JavaDocとか言ったり、javadocというツールのことだったり、 Javadocが何を指してるのかよく分からなくなることもしばしばあるけれど、とりあえずそのことについては考えずにここではJavadocの表記で統一します。

Java SEのAPI仕様は見たことあるはず。

http://docs.oracle.com/javase/jp/8/api/ ←こいつのこと

HTMLで出力したものをWebブラウザで見るので、コメントの本文はHTMLタグでわかりやすくマークアップしなければならない。

また、Javadocタグを使えることろは積極的に使う。そうすれば、ドキュメント間のリンクとかもやってくれる。タグは頑張って覚えよう。そんなに種類もないし。

読み方を考えてみる

Javadocコメントを読む方法は以下の3つに大別できる。

一つは先にも挙げたように、インターネットを介して閲覧する場合。 Java SEやOSSライブラリのドキュメントを読むときはこの形が多いだろう。また、ドキュメントの記述量が多い場合、IDEで読むのはつらいのでこの読み方をする。

次に、IDEで使用するクラスやメソッドのドキュメントを参照する場合。この用途では、メソッドのコメントを読むことが主になる。 HTMLで読むものと対象は被るが、コーディング中ならばこちらの方法で読むと思われる。利用するライブラリのソースが必要だけれど、たいてい xxx-sources.jar は手に入るから心配いらない。

最後に、ソースコードを直接見る場合。自分たちで開発しているコードのドキュメントコメントはこの形で読むことが多い。というか、わざわざHTMLで見るなんてしない感じ。 APIとして利用を想定されていないクラスやメソッドのコメントを読む場合もこれになる。この見方だと、ドキュメントコメント以外のコメントやコードも目に入ってきます

書くことを考えてみる

では何を書けばいいかだけれど、昔はこんなこと書いてた。

このコメントに書かれていて嬉しいことは「何が達成できるか」です。どのように使うと、どうなるかをさくっと把握できるのがベストです。このコメントを読む人がコードを読むことはそれほど考えなくていいです。

これは一番目、二番目の読み方をする時に言えることで、三番目の読み方をする場合はコードと並べて読むこともあり、書く内容も変わる。書く内容は非ドキュメントコメントに近いと思われ、実装理由やコードの要約が適切かもしれない。

読み方から書く内容は決まるかなと思ったのだけれど、読み方分類では書く内容を考えづらい。なので、読み方よりも読者視点で書くことを考えてみることにする。

読者を考えてみる

コメントの想定読者は利用者と保守担当者くらいが考えられる。これらの想定読者によって、書く内容も変わってくるはず。

想定読者が利用者、つまり公開APIのドキュメントコメントは、それが何ができるもので、どのように使い、何に気をつければ良いかを記述する。サンプルコードがあると良いことも多いのだけれど、コメントはコンパイルできないし、基本的にリファクタリングに追随して修正されたりもしない。ゆえに嘘になりやすく、誤ったサンプルコードを提示してしまう危険と隣り合わせになる。それでもあって助かることも多いので、メインとなる公開APIには書いていきたいと思う。

想定読者が保守担当者、つまり公開APIを除く全てのドキュメントコメントは、それが何ができるものかは同じだけれど、設計判断や拡張時に気をつけるべきことを記述する。関連が強いクラスへのリンクをしっかり書いておくと助かることも多い。 privateのドキュメントコメントを書く場合、ほぼ間違いなく保守担当者向けだろう。

ドキュメントコメントにHTMLを使うべきか

素直に「JavadocコメントはHTMLでマークアップするもの」とやってしまうと、主となる読者が「そのコードを保守する人」であるならば、HTMLは邪魔になる可能性が高い。人間の目はHTMLを解釈しないので、プレーンなテキストの方が読みやすい。また、コードを修正する時もHTMLタグを書くのは面倒だったりする。

想定読者が保守担当者のドキュメントコメントにHTMLを使用すると、苦労して書いて、苦労して読んで、苦労して修正することになる。誰も嬉しくない。そんなことがあるので、「HTMLを使うべきか」と問われると「状況によるし、使わなくてもいいんじゃないかな」になる。

とはいえHTML的に不正な状態だと文句言われるし、多少配慮はしたほうがいいかも。