私が書いて欲しいと思うコメントとして、前回
は「見出しとしてのコメント」について述べた。今回は、もうひとつ、「注釈としてのコメント」について書いておこうと思う。
注釈とは
そもそも「注釈」は「comment」の訳語のひとつであり、「ソースコードのコメント」としても、最も一般的な用途でもあるだろう。
「Yahoo!辞書 - 大辞泉
」によると、注釈とは「語句の意味や用法を解説したり、補足的な説明を加えたりすること。また、その説明。」である。ソースコードに書く場合にも、本質的な違いはないだろう。
注釈を書く目的は、読者の理解を助け、誤解のないようにすることである。まず、プログラマは、このことを忘れてはならない。
過不足なく書く
「注釈としてのコメント」を書く上で最も注意すべきは、過不足なく書くということだ。
必要なコメントを書かなければ、コードが「何をしたいのか」ということを読者に伝えることができない。逆に、無用なコメントを書けば、コードが読みにくくなるし、将来的に「嘘（コードと不一致）」になる可能性も高くなる。
コメントを書く時には、常に、「もっと必要なコメントがあるのではないか」とか、「今書いているコメントは本当に必要なのか」ということを、読者の立場に立って、よく考えなければならないだろう。
コードで表現できないことを書く
「その１
」で書いたように、無用なコメントを書きすぎる人は多い。そして、そのことが、コメントは書くべきでない（書かなくても済むのなら、それが理想だ）といった、コメント無用論を生んでいるように思う。
コメント無用論の核となっているのは、「コードを読めば分かることをコメントに書く必要はない」という主張である。それ自体は正しいだろう。しかし、それは裏を返せば、「コードを読んでも分からないことは、コメントに書くしかない」ということでもある。
例えば、
// CR + LF を LF に置換
data = data.replaceAll("\r\n", "\n");
これは不要なコメントだ。「コードを読めば分かること」しか書かれていないからだ。
では、次のようなコメントはどうだろう。
// Windows 98 では化けるので（Me/2000/XPでは化けない）
data = data.replaceAll("\r\n", "\n");
「コードを読んでも分からないこと」が書いてある。つまり、もし、このコメントを削除したら、その情報は欠如してしまうということである（※２）。
コメントには「HOW」ではなく「WHY」を書けと言われるが、このような例は、それを端的に示している。HOW（どのように処理しているか）は、コードそのものから読み取ることが出来る。しかし、WHY（なぜそのような処理をしているのか）は、コードからは読み取れない。
読者に伝えたいこと、伝えるべきことがあっても、プログラミング言語だけでは表現できない。そういうときに、注釈としてコメントに書く。当り前といえば当り前のことである。
どう書くか
「HOW ではなく WHY を書く」という考え方は、「注釈としてのコメント」を書く上での枠組みを示してくれる。
しかし、それだけで上手く書けるようになるわけでもない。言葉の選び方、文章の書き方など、悩みながら書くことになる。ここでも、文書作成の能力が問われるところである。
※１
注釈をどこまで書くかということは、あくまでも読者の立場で考えるべきである。例えば、読者がそのシステムの設計や仕様をどの程度理解しているのか、技術的なスキルがどの程度なのか、といったことが関係するだろう。チーム開発では、チームの他のメンバーを読者として想定するといいだろう。読者が不特定多数の場合であっても、どこかに「読者層」を想定しなければ、コメントの細かさの点で、一貫性がなくなってしまうだろう。
※２
トラックバックでも指摘されているが、以前は、この部分に、不適切な例（WHY になっていない例）を記載していた。この記事を新しく読んでくださる方のために本文を修正し、修正前の内容は以下に残すことにした（2005/09/10）。
例えば、
// システムプロパティの "swing.noxp" に "true" を設定する。
System.setProperty("swing.noxp", "true");
これは不要なコメントだ。「コードを読めば分かること」しか書かれていないからだ。
では、このコメントは消してしまえばよいのだろうか？
これは Java のソースコードである。しかし、Java プログラマの中にも「コードを読んでも何をしているのか分からない」という人は多いのではないだろうか。少なくとも自分がそのように判断するのであれば、「注釈としてのコメント」を書くべきだろう（※１）。
同じコードでも、次のようなコメントが付いていればどうだろう。
// Windows XP でも、従来風のデザインで画面を表示する。
System.setProperty("swing.noxp", "true");
これなら、そのコードが「何をしたいのか」ということがよく分かるのではないだろうか。
■関連記事
・もっとコメント論 ～その１～ コメントとは何か
・もっとコメント論 ～その２～ 見出しとしてのコメント
・もっとコメント論 ～その４～ システムの開発や保守のために
・もっとコメント論 ～その５～ コードが求めるコメント
講談社 (2004/05/21)
売り上げランキング: 1,915
本当に「わかりやすい」です 相手の立場に立った分かりやすい文章
1冊だけでも十分
アスキー (2003/11)
売り上げランキング: 10,396
ハッカーになる入門書 本当のプログラマになるためには