輝々凛々

ガンバるってことは、素晴らしい事だ。

どんなコメントをつけるべきか

プログラム中にはコメントを書きましょう」というけれど、
どんなことを書けばいいのかよくわからないから書けることを全部書きました。


というのは、私のことですが。
今日は「どんなコメントをつけるべきか」について。
ま、結論から言いますと

コメントは「何をしているか」を書くのではなく
「何故そうしているか」を書く。


ソースコード中がコメントだらけになると、逆にソースが読みにくくなるのは当然で
たとえばソースコードの半分がコメントだったら、
いったい何をしているのかわかりません。
本当にそれはプログラミングですか?

というわけでソースコード中のコメントは20~30%くらいにしようと
先週あたりから心がけてます(おぉっ


で。
「何をしているか」を今までは書いていたのですが
これがキリがない。
そんなものソースコードを読めばわかるようにコーディングするべきだし
ソースコードに変更があったときにコメントも直す必要が出てくる。
それでコメントの修正忘れなんて話もよくあるのさ!


そんなわけで「何をしているか」コメントを書きません。
(まぁ、関数が何をしているか、ぐらいは書きますが逐一説明はしません。
 あるいは何かややこしいことやっているなら説明したらいいと思います)


で、代わりに「何故そうしようとしているのか」を書きます。
 どんな理由があってそんなことをしようとしているのか。
 どんな理由があって普通の書き方をしないのか。
そんなことを書きます。
んー、ちと難しいかなぁ。

たとえば!
以下のようなコードでは
 「なんで逆回しなのか」とか
 「なんで前置デクリメントなのか」とか
そんなことをコメントしています。
// 逆順で出力したいので10からデクリメントしていく。
// 今後イテレータに変更することを考えると前置デクリメントにしておくほうが良い(一時オブジェクトが作られないように)
for (i = 10; i > 0; --i) {
  // do something
}



とか。
まー。こんな感じです。
何か意見がありましたら、よろしくお願いします。
関連記事

ツッコミの投稿


(ツッコミ非公開の場合はチェック)