WebKit 開発者のメーリングリスト webkit-dev を見ていたら、興味深い話題で盛り上がっていた。WebKit のソースコードや ChangeLog のコメントに関する議論だ。
WebKit に限らず、ハッカーというのはソースコードにコメントを書きたがらない。
コメントが古くなってしまい、実情と合わなくなってしまうから、というのが理由としてはよく聞かれる。すぐ古くなってしまうコメントを書くより、元々コメントを書かなくて済むような綺麗なコードを書けよ、とハッカー達はよく言う。
個人的には、コードでは処理の内容は記述できるけれど、意図を記述できないので、意図を補足するコメントぐらいは必要なんじゃないか、と思っているけれども、それすらダメと言う人も時々見かける。
ともかく、今回の議論は自分にとっては興味深かった。
そこでその内容を紹介してみようと思う。
議論はいくつかのトピックに分かれていて、それぞれ別のスレッドが立っている。
事の発端は、皆さん change log に関数レベルのコメントを書きましょう、というもの。
http://www.mail-archive.com/webkit-dev@lists.webkit.org/msg19771.html
http://www.mail-archive.com/webkit-dev@lists.webkit.org/msg19775.html
WebKit では修正をコミットするときに ChangeLog というファイルに追記する決まりになっていて、その内容についての話。
WebKit の場合、この ChangeLog の内容はレビューをしてもらう時にも参照され、レビュアーに修正の意図や設計を伝える役目も担っている。
- 最近 change log に修正の概要しか書かない人が多いけど、みんな関数単位のコメントを書いてよ。レビューの時も、後でコードを調べる時にも役に立つからさ。
だがここから話は別の方向に飛んでしまう。ソースコードにクラス単位のコメントを書くべきかどうか。
http://www.mail-archive.com/webkit-dev@lists.webkit.org/msg19778.html
- WebKit のような巨大で複雑なコードベースで、「コメントを書かないで済むように綺麗に書けばいい」とか幻想だろ。クラス単位のコメントがないせいで、どのクラスが何やってるのかわからないし、クラス間の関連もわからない。
- 以前の議論では、クラス単位コメントには大半の人が賛成していたよ。コード中のコメントも、意図を説明する内容であればOK。
- 一連の手順を説明したコメントは、適切な名前の関数で置き換えられるよね
- 事前条件、事後条件についてのコメントは ASSERT にしたほうがいいよね
- クラスの ownership や lifetime relationship についてドキュメント化するのはいいね。図を描いてそれへの参照をコメントに書いておければいいけどねー。
- クラス名はなるべく自己説明的なものにすべきで、コメントは最後の手段だよ。
- 自己説明的でかつ簡潔な名前を付けるのは難しいときがあるから、コメントが必要なときもあるでしょう。例えば、JSGlobalData がなぜ必要かを説明する良い名前は難しいから、コメントあったほうがいい。AffineTransform はいらない。
- 「コメントは書くべきでない」という文化があることで、それがプレッシャーになって、クラス名について一生懸命考える。それによって、良くない設計に気付いて見直したりすることもある。
- インセンティブ重要。コメントは書くべきでないというプレッシャーがないと、気が緩んだり、時間がないとかの理由で安易な名前にしがち。
- 本当にインセンティブ重要だよね。コメントが間違っていてもコンパイラはチェックしないから、誰も直そうというモチベーションにならない。だからコメントは書かないほうがよくて、別の手段を考えるべき。
- コードのコメントを最新に保つのは確かに大変だ。change log にコメントを書くやり方はよいと思う。change log は特定のリビジョンについての記述だから。
- 少なくとも JavaScriptCore については、打つ手はない。他も同様じゃないだろうか。JavaScriptCore の中枢部分はよく変更されるので、
- コメントを書けば、古くなる
- change log を書けば、(大量の変更履歴に)途方に暮れる
結局、コードの難しい部分については、読むしかないんだと思うよ。
まとめるのに時間がかかってしまったので、他のトピックは明日取り上げよう。
かなり意訳してるけど、大幅に間違っていたら指摘ください ＞ 読者の方。
