コンピュータが理解できるコードなら誰でも書ける。優れたプログラマは人間が理解できるコードを書く。

マーチン・ファウラー -『リファクタリング―プログラムの体質改善テクニック』

よく「コメントをきちんと書け」ということを言われます。そのためか、初心者の書いたソースを見ると、必要以上に大量のコメントが書かれていることがあります。確かに全くコメントのないプログラムには読みにくいものが多いのは確かですが、何でもかんでもコメントをつけるのも同じく間違っています。余分なコメントは、プログラムとコメントの不一致、いわゆる「嘘のコメント」の原因になります。要するに「必要十分」なコメントを書くことが大切なのです。

といっても、どのようなコメントが「必要十分」なコメントなのかということに関して決まったルールがあるわけではありません。よく言われるものとしては、

• if, while等の条件分岐箇所にコメントをつける
• 関数の先頭に、引数や戻り値、処理内容のコメントをつける
• 外部制限による注意を書く（HW制御手順等）
• 一連のアルゴリズムの説明を書く(リスト中を二分探索するとか、ユークリッドの互除法は最大公約数を計算する等)

というあたりです。
しかし、これらに関してもソースコードを見てすぐに理解できる範囲であればコメントを書く必要はありません。プログラムの情報を補うのがコメントの目的ですから、補うべき情報がなければ書く必要はないのです。見方を変えると、コメントを付け加える前に、ソースの変更によってコメントを書かなくても分かるようにできないかと考えるべきです。 次に例をあげます。

bool flag = false; /*全タスクが終了しているかを示すフラグ*/

/* 全てのタスクが終了するまでループ */
while (!flag) {
  /* 各タスク状態のチェック */
}

この例の場合、コメントがないと、while分からは「何らかのflagがfalseの間はループしている」ということしか伝わらりません。よって、コメントはプログラムを補っているということで必要性がありそうに思えます。
しかし、落ち着いてよく考えてみると、そもそも「flag」という何の変哲もない変数名をつけたことがまずいのではないでしょうか。よって、次のように書いていれば、コメント無しでも十分意味は伝わります。

bool all_task_finished = false;

while (!all_task_finished) {
  /* 各タスク状態のチェック */
}

もうひとつ例をあげます。

/* 2つの矩形エリアrect1とrect2にx,yが含まれる場合*/
if ((x >= rect1.x1 && x <= rect1.x2
     && y >= rect1.y1 && y <= rect1.y2)
     && (x >= rect2.x1 && x <= rect2.x2
         && y >= rect2.y1 && y <= rect2.y2)) {
  /*処理*/
}

このままでは、条件式が長いのでコメントが必要になっています。これも、

/* 2つの矩形エリアrect1とrect2にx,yが含まれる場合*/
bool is_in_rect1 = (x >= rect1.x1 && x <= rect1.x2
                    && y >= rect1.y1 && y <= rect1.y2);
bool is_in_rect2 = (x >= rect2.x1 && x <= rect2.x2
                    && y >= rect2.y1 && y <= rect2.y2);
if (is_in_rect1 && is_in_rect2) {
  /*処理*/
}

とすることでコメント無しでも意味が伝わりやすくなります。このように、関数分割しなくとも、処理結果を適切な名前の変数に代入するという方法で、可読性をあげるのも一つの手法です。

なお、これらの例の場合は、無理にコメントをなくさなくとも良いとは思います。重要なのは、極力コメントを書かないという点ではなく、コメント付与の前に、コード側に問題がないかを考えることなのです。コメントを付与することは、情報をコードとコメントの二箇所に分散させることになるため、一貫性を保つ必要性が出てしまうということを忘れてはいけません。

なお、関数の仕様等はコメントとして書いた方がよいと思いますが、この場合も、doxygenやjavadocの形式で記述することで、仕様書とコメントの両方に情報が分散することを防ぐことができます。情報の分散、二重管理は何かと問題を引き起こすので、しないで済む分はしない方が無難です。私がハンガリアン記法が好きになれないのも型情報が二重管理になっている点です。

最後にまとめるとすると、

• コメントを必要最小限に
• コメントが必要そうだと感じた場合は、プログラム側に問題がないかと疑う

ということです。

【関連記事】
・英語のコメント
・ドキュメントの自動生成
・変数の命名規則

【関連リンク】
・コメント論（悪態のプログラマ）
・実効的コメント書方（Cプログラミングの秘訣）
・doxygenを使おう

【関連書籍】
・文芸的プログラミング Donald E. Knuth
・リファクタリング―プログラムの体質改善テクニック
・プログラミング作法