なぜコメントの付け方の昔と今が違うかと言えば、原因は二つある。

cover
Perl Best Practices
 Damian Conway
[邦訳:Perlベストプラクティス]
小野和俊のブログ:ソースコードのコメント率は20%を切ることが望ましい
昔はソースコードのコメント率が50%を切るものはドキュメント不足で品質が低いものとされた、という内容のものがあった。
[中略]
今、改めて考えて、どのような言語であってもどのようなコーディング規約であっても、私はソースコードのコメント率は原則20%を切ることが望ましいと思う。

まずは言語仕様そのもの。昔は変数名の長さに限りが合ったり、loop controlにifとgotoしか使えなかったりで、「プログラムそのものに語らせる」ということが非常に難しかった。だからそのcodeが何をするのかを、codeとは別に書き記しておく必要があった。

今時の言語は、その制約からかなり解き放たれている。すでに若いCでさえ、変数名は255文字程度、すなわち実質上長さを気にしないで使えるし、これがOOP言語だとさらにクラス名が加わることで、その変数がどこのなにがしかはすぐにわかるようにしやすくなっている。loop controlもforとwhileがあるのでgotoももはやほとんど使わない。ましてや今時のLLはifやunlessやforやwhileまで後置できるのだ。

codeそのものが饒舌になった今、それこそコメントは「蛇足」というものだろう。

もう一つは、「コメント」と「ドキュメント」が分離されたこと。両者の違いは何かというと、前者は「薬の科学成分と合成法」、そして後者が「使用上の注意」。薬を飲む人に必要なのは、明らかに後者であって前者ではないのだが、昔は大きなプロジェクトでは「ソース」とは別枠でそれを用意するか、そうでない場合はコメントにそれが延々と書いてあったりした。

これに対して、今では単一のファイルでもソースはソース、ドキュメントはドキュメントときれいに分けて記述できるような工夫が増えてきた。その嚆矢はPerl 5のPODだと思われる。PODとはPlain Old Documentの略ということになっていて、なるべく書く側の手間を省くようなシンプルなマークアップ言語となっているのだが、なかなかどうしてその記述力は高く、私が本や雑誌原稿を執筆する時にはたいていこれを使っているぐらいだ。同じファイルに書いていいので、今までコメントを付けるのとさほど変わらぬ手間でドキュメントを書けるようになった。

CPANで何かを配布する際には、このPODの記述があることが強く推奨される。codersは単にcodeを書くだけではなく、そのcodeの取扱説明書をきちんと書く事を求められるわけだ。PODの分量はものによっても異なるが、codeよりも多いものも珍しくない。

このPODに似た様式によるドキュメンテーションは、javadocやRDにも受け継がれている。

注目すべきは、Perl Communityは取扱説明書の添付は強く求めても、コメントの書き方に関しては何も言っていない事だ。これはやんわりと「不要」と言っているに等しい。実際私はほとんどコメントを書かない。書いたら負けとすら思っている。もしコメントなしではそのcodeが理解できないのだとしたら、それはcodeに語らせることに失敗しているのだ。

例外がないでもない。

小野和俊のブログ:ソースコードのコメント率は20%を切ることが望ましい
ソースを読んだだけではすぐにわからないようなアルゴリズムを採用している場合や、使用しているライブラリのバグ回避のための特殊な処理を行っている場合、または他の人が見たときや自分が数年後に見た時に「なぜここでこんなことを？」と感じる可能性がある場合にはソースコードにコメントを追加するべきだ。

これは、Perl Best Practicesでは、以下のように紹介されている。

Comment that has puzzled you or tricked you.
あなたが迷ったり勘違いしたところをコメントせよ

ここで注意して欲しいのは、主語が「あなた」になっていることだ。「読者が迷ったり勘違いしたりしそうな」ではないのだ。そう。コメントはあくまでも自分、少し広げてもXPのパートナー用にとどめるべきで、一般読者には取説を用意するべきなのだ。

その他にも、Perl Best Practicesの第七章には、ドキュメンテーションに関する知見が満載だ。Perl以外でも使えることが本章以外にもたくさん書いてあるので、。最近日本語版も出たことだし、Best Practiceを指向するプログラマーは是非入手して欲しい

Dan the Commenter