ognac氏のエントリに始まるコメント談義。私なりのまとめをひとつ。

対訳型コメント

プログラムのやりはじめには自然言語で考えて、プログラム言語に翻訳する過程を経てプログラムを記述します。
慣れてくると最初からネイティブにプログラム言語で思考してそのまま記述するようになるのですが、翻訳過程を経ているうちは、1行のコードに対して元になる自然言語を対訳としておいておきたいことでしょう。

本稿ではこのようなタイプのコメントを対訳型コメントと呼ぶことにします。

ognac氏のエントリで例に挙がっていたのは

a = (b + c) /2 ' bにcを加えて2で割る

といったものでした。シングルクォーテーションによるコメントだから言語はVBかな？

プログラム言語というのはプログラムの記述に適しており、自然言語でそれを表現しなおすとスマートではない記述になります。 1行1行に対訳を置いていくのはプログラム言語を読めない人間には読解の手助けにはなるかもしれませんが、そもそもが冗長なものです。プログラミング言語を読解できるのであれば、プログラムの表現に向かない自然言語での冗長な説明はむしろ邪魔なのです。
意義あるコメントが中に含まれていたとすれば、コメントを隠すならコメントの中とでも言いますか、無駄なコメントに埋もれて用を成さなくなってしまう。

レ点型コメント

対訳するようなものは冗長で不要というのが基本的な姿勢なのですが、言語の構文の中でも特殊で読みにくいものも中にはあったりしますし、プロジェクトチーム内に技術レベルの低い人間が多いこともあるでしょう。

そういった場合でも1対1の対訳コメントは避けたい。そこで読解の手助けとなるレ点型コメントを記述することになります。レ点というのは漢文についている読解の補助とするためのレ字の記号。下から上に戻って読む場合につけます。

レ点型コメントとしては、検索しやすいようにキーワードを提示しておくなどするとよいでしょう。

マーカー型コメント

コードと1対1となるコメントでも時には有効な場合があります。なにか重要な処理をしている場合、その位置を示すためにコメントを記述することがあります。これをマーカー型コメントと呼んで対訳型コメントとは区別しましょう。

// ActionListenerの登録
this.addActionListener(listener);

マーカー型コメントを生かすには、周囲に対話型コメントが存在しないことが必要です。あるいは、目立たせるためにアスキー装飾されることもあります。

// --------- ActionListenerの登録 ---------
this.addActionListener(listener);

やりすぎは鬱陶しいのでほどほどにするべきでしょうけども。

要約型コメント

次に考えられるのは、要約型コメント。これは、ソースコードの塊が何をなそうとしているのかその要約を記述するもの。

ognac氏のエントリでは、先の対訳型コメントを要約型に直し、

a = (b + c) / 2 'aはb,cの算術平均

としていました。1行コメントでは分かりにくいですが、数行に渡るコードに対して、その塊全体で何を行おうかを記述するものです。
要約をコメントすることで具体的なコードを追う前に要約を知ってから読むことが出来るため、コードの読解の手助けになります。

また、バグがあった場合、要約が記述されていると直すべき方向性がはっきりするので修正がしやすい。ところが、対訳型コメントしかない場合は、その一連の流れのコードでなにをしたいのか、行間を読んだ上で「こういうことがやりたいんだろう、きっと」という推測の元に直すことになります。
そもそも何がしたいのか不明な場合はソースを丸ごと破棄せざるを得なくなります。

要約というと難しいかもしれませんが、要するに意図を記述するのです。自分はこういうつもりでコードを書いているんだ、ということをコメントにしておく。そうすることで、他の人にも意図を汲み取った修正が可能になる。ここで言う「他の人」には未来の自分も含まれることをお忘れなく。過去のコードを書いたときの心情なんて覚えてられないのでもはや他人が書いたコードに等しい。

javadocコメント

ちょっと言語が偏りますが、Javaにはメソッドなどに特殊なコメント記述方式を使うことで自動的にリファレンスを生成する機能性を持っています。以前の エントリで紹介しているので詳細は省きます。なお、.NETにも同様の機構があります。こちらはやまださんが まとめてくれています。

要約型コメントのまとめに近いものがあります。メソッド単位での要約とも言えましょう。それに加え、引数の意味、返り値の意味といったインターフェース定義の役目も担っています。そのため、契約に基づくプログラミングにおいて重要な役割を果たします。

言語に特にそのようなコメントの記述方式がある場合はそれを利用すべきです。

メモ型コメント

メモ的にコメントを残すことがあります。
「ここは共通化したい。メソッドに切り出すべき」
「パフォーマンスが不安。性能劣化するようならパフォーマンスチューニングを考える」
「将来的にStrategyパターンで書き換えたい」
などなど…

Eclipseの場合、「TODO」というキーワードをコメント中に残すと、後で一覧にして見ることが出来ますから、TODOコメントを残すことも多いですね。これもメモ型コメントと言えるでしょう。

追記：理由型コメント

そのソースを見ただけではなぜそのような作りになっているのか分かりにくい場合に その理由を記述するタイプのコメント。
場合によっては要約型コメントと重複することも。

一見して凄くトリッキーな、もしくは無駄なことをやっているように見えて、 バグ回避のためのハックであったり、政治上の理由でやむを得なかったりといった ドラマがそこにある場合があるのです。

こういったプログラムの範疇外との接合部分はそれこそコメントでしか示せません。

追記：コメントアウト

コメントであってコメントではないのがコメントアウト。 ソースを一時的に（あるいは無期限だったりもする）無効化させるために コメントにしてしまうこと。

別稿で述べていますが、今となっては無用の長物。