前回に引き続き、コメントの付け方をさらに分析してみた。 

自分の考えをコメントにする

コメントは、コードを書いている時に考えていた課題や意図、TODOをコメントにすべきとのこと。見てわかることは書く必要がない。

確かに、プログラムは一度作ったら終わりではなく改修/保守していく。その時になぜこのコードを書いたかがわかれば、エラーの原因特定やチューニングの助けになる。自分だけでなく他の人の役にも立つことだから取り入れていこう。

読む人が驚くポイントにコメントをつける

パッと見では伝わらないコードはコードを直すべきだが、直しても伝わりにくいコードはどうしても出てくる。その時はコメントで説明しよう、ということだが、客観でコードを見ないといけないからなかなか難しそうだ。

コメントどうこうより、客観でコードを見る力が不足している気がするので、そっちの方が優先だな。

情報密度の高いコメントをつける

例えば、以下のようなコメントがあったとしよう。

// このクラスには大量のメンバがある。同じ情報はデータベースにも保管されている。但し、
// 速度の面からここにも保管しておく。このクラスを読み込むときには、メンバが存在してい
// るかどうかを先に確認する。もし存在していれば、そのまま返す。存在しなければ、データベー
// スから読み込んで、次回のためにデータをフィールドに保管する。

こうではなく、以下のように書けばいい。

// このクラスの役割は、データベースのキャッシュ層である。

引用元：Dustin Boswell, Trevor Foucher『リーダブルコード』オライリー・ジャパン出版

慣れ親しんだ言葉を使うことで文章を単純化するのは必須だな。長くてくどいと読んですらもらえないだろうから。

そのためには情報密度の高い言葉を扱えるよう、本を読んだり人と会話をして語彙力をつけないといけないな。ゴリ力ならあるんだけどね。