2006年09月04日 15:15 [Edit]

コメント!=ドキュメント

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

小野和俊のブログ:ソースコードのコメント率は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


この記事へのトラックバックURL

この記事へのトラックバック
こんにちは、林です。今回の記事では、「ソースコードに書くコメントは必要最小限が良いか」という命題について考えてみたいと思います。 コメントは最小限が良い? 巷の書籍やブログ記事で、優れたプログラマによる以下のような記事をよく目にします。(うちの会社でも良く...
コメントは必要最小限が良いか?【TriAx Lab】at 2010年07月27日 23:54
めずらしく釣りっぽいタイトルだけど、ちゃんと主張しておきたいので。 きっかけはこちらの記事。 極論すると、コメントが無いと読めないコードはダメ - かおるんダイアリー ここから色々リンクを辿ってみたけど、ほとんどの人が コメントを書かなくてもいいよう、十分明確
「いいから黙ってコメント書け」という話【miauの避難所】at 2009年09月16日 03:48
この記事へのコメント
それはともかくとして。
今日ビックリさせられる事があったのでちょっと聞いてくれよ。

お堅い系顧客のPHPソース・メンテナンス(遠隔地共同作業)で、
「他の人と同様に変更コメントを書いてくれ」と頼んだら、
不服そうな顔をしているんで尋ねると
「ライブドアではコメントを書くのは良くないとされている」
とか言い出すんですよ。
別に超絶コーダーを呼ぶほどの仕事頼んでないし、頼んでも無理っぽい状況で。

お堅い系顧客の仕事ってのはソースを長年使いまわす傾向があって、その間に拡張/保守担当の人や会社が変わることも多いから
変更履歴をコメントで入れとくのがマナー。
そんなTPOをわきまえない人が、Dan氏の発言鵜呑みにして
勘違い振り回すこともあるんだって事を、自覚してほすぃ
Posted by 通りすがり at 2007年09月13日 20:40
私自身は、Perlなんて所詮書き捨てるものでしかないので、
コメントなど重視しませんが・・・まぁJavaやCなら普通書きますね。
仕様やアルゴリズムをそこいらの裏紙に殴り書きして(ファインマンスタイル)、
次におもむろにソースを書き始め、迷いそうになったら仕様メモやらアルゴリズムメモを
ソース中にコメントとして書いて、その間にコードを埋めていくとか、
場合によってはUMLで設計しなおして頭の中を整理するとか。
Posted by 通りすがり at 2007年09月13日 20:36
それと,「間違ったコメントなら無い方がマシ」ということもある.コメントはコンパイルエラーにもバグにもならないので,本体のコードを変更するとすぐに obsolete になってしまう.といってコードが安定した頃になって後付けでコメントするのも虚しいし,その頃には別のコードに取り掛かっていることだろう.結局ここで言っているように危険な部分にコメントするってのがまさに best practice なんだろう.
Posted by anonymous at 2006年09月05日 01:32