コメントには「何をやっているか」ではなく「なぜそうしているか」を書く

　私は学生時代はソースコードにコメントを書くのが苦手でした。逆にそのおかげで「コメントがなくても読みやすい」コードを書くよう心がけるようになったのですが。

　さて、社会人となり、あまたのソースコード軍曹のおかげで私もそれなりのコメントがかけるようになった今日この頃ではありますが、何年やっても依然としてコメントを書くのが下手な人がいますね。

　最悪なコメント例（実際に見たことがある）

// フラグを立てる
flag = 1;

　これ見たときはびっくりしましたよ。フラグ立ててるのなんてコード見りゃわかるわー！と突っ込みを入れちゃいましたよ。

　私ならこんな感じで書きますね。

// 処理済を表わすためフラグを立てる
flag = 1;

　このように「なぜ」が入ると飛躍的にコメントがわかりやすくなります。

　逆に「なぜ」が書けないようだと危ないです。よくあるのが、上級者が書いたコードをまねしたり、他プラットフォームからの移植のとき。「なぜ」が書けないということはもとのコードを読み切れてないってことですからね。