コメントは書かなくていい　Javadocを書いてくれ

会社のとあるプロジェクトでコーディングの可読性に関する勉強会を実施してるらしい。
そのプロジェクトはリリースは終わって保守に移行してんだけど今更そこ勉強してんのって感じが半端ない。新人向けか？
そのプロジェクトはもちろん炎上しまくってた。今も炎上してると思う。

さて、その勉強会の資料を見る機会があってだいたいはごくごく当たり前のことを書いてた。メソッドの行数とかそういうの。
でも資料の中にコメントを書けっていう項目があってJavadocを書けって言う項目がなかったのに驚きを隠せなかった。
コメントなんかよりJavadocの方が大事なんだってことがわかってないみたい。 というか、そのプロジェクトではJavadocを書かない主義だったらしい。全く意味がわからない。恐ろしい。。。

と、前置きが長くなってしまったが、 コメントを書くよりJavadoc（privateメソッドも含む）を書く方がいいんだってことをざっとまとめてみようと思う。

Javadocの方がコメントよりも何を書くべきかがはっきりしている

Javadocの方がフォーマットが決まっているし、メソッド全体についてのコメントを書くようなものなので、 意味のない情報を書くことが少ない。

意味のない情報って何か？例えばこういうの。

i++; // 値を１だけ増加させる

こういうのを書いてしまうのはコード一つ一つに対してコメントが必要だと思っているから。 たとえコメントは重要なことだけ書けって言われたって、何が重要なのかは経験積まないとわかんないと思う。

Javadocの方がコメントがまとまっているのでコードが読みやすい

コードの途中にコメントが散在しているのをよく見かける。
これすごく読みづらい。特にコメントをコードの横に書いていないものは。

例えばこういうの。

// オブジェクトの数だけループする
for (int i = 0; i < objs.length; i++) {
    // オブジェクトが有効である場合
    if (objs[i].isValid()) {
        // 実行用のメソッドを呼ぶ
        objs[i].exec();
    }
}

Javadocだと別途ドキュメントを生成できる

ソースコードから仕様書を作成できるって言うのがJavadocの魅力だよね。
privateメソッドであっても別途ドキュメントできるのはいいことだ。

仕様書とソースコードを別々に管理したがる人っているんだろうか？
管理が大変だからできるだけソースコード中に仕様書を書くようにすべきだと思う。 もちろん基本設計仕様とか上流のものなら別文書で管理してもいいけど。

最近読み返していた人月の神話にも仕様書は別管理すると大変だからソースコードに書けみたいなことが書いてあった。

Javadocを書くことを意識した方が良いコードが書ける

コメントは多すぎても少なすぎてもいけない。 コメントが多い人の特徴はコードがまとまってなくてコードがわかりにくいためそれをコメントで補うということをしてる。 また、コメントを大量に書く人はメソッドを長く書く傾向にあると思う。

例えばこういうの。

public void doSomething() {
    // xxxオブジェクトから繰り返しデータを取得する
    // 取得するのはこれこれの理由があるため
    ...
    ...
    ...

    // oooオブジェクトにデータを設定する
    // 設定するのはこれこれの理由があるため
    ...
    ...
    ...

    // fooとbarを実行する
    ...
    ...
    ...
}

普通は各コメントに書いている処理をprivateメソッドに切り分けるべきなんだが、 コメントを書いているからということでprivateメソッドに切り分けることを横着してる。 こういう場合はprivateメソッドに切り分けてきちんとJavadocを書かないといけない。

まとめ

publicメソッドは基本的にはJavadocが必須（もちろん例外もある、例えばgetter/setterとか）でprivateメソッドは任意。 でも、コメントを書くぐらいならprivateメソッドでもJavadocを書いた方がメリットは大きい。 だから、なるだけJavadocを書く、ということを意識した方がいい。 もちろんコメントを書いたほうがいい場合もある。だから優先度的には下のような順かな。

1. Javadocを書く
2. Javadocに書くことようなことでもないが、 重要なこと（ここが曖昧だが、ToDoとかどうしてもわかりにくい処理とか）はコメントを書く