『リーダブルコード』第6章コメントは正確で簡潔に

鍵となる考え方：コメントは領域に対する情報の比率が高くなければいけない

コメントを簡潔にしておく

シンプルに説明できることをダラダラ書かない。

// int は CategoryType。
// pair の最初の float は 'score'。
// 2 つめは 'weight'。
typedef hash_map<int, pair<float, float> > ScoreMap;

↓

// CategoryType -> (score, weight)
typedef hash_map<int, pair<float, float> > ScoreMap;

あいまいな代名詞を避ける

// データをキャッシュに入れる。ただし、先にそのサイズをチェックする。
↓
// データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。

歯切れの悪い文章を磨く

コメントを正確にする。

// これまでにクロールした URL かどうかによって優先度を変える。
↓
// これまでにクロールしていない URL の優先度を高くする。

関数の動作を正確に記述する

// このファイルに含まれる行数を返す。
↓
// このファイルに含まれる改行文字(‘n’)を数える。

入出力のコーナーケースに実例を使う

関数・メソッドの機能を全て見せることのできる実例をコメントで示す。

// 'src' の先頭や末尾にある 'chars' を除去する。
String Strip(String src, String chars) { ... }

↓

// 'src' の先頭や末尾にある 'chars' を除去する。
// 実例:Strip("abba/a/ba", "ab") は "/a/" を返す
String Strip(String src, String chars) { ... }

コードの意図を書く

// listを逆順にイテレートする
for (list<Product>::reverse_iterator it = products.rbegin(); it != products.rend();
    ++it)
    DisplayPrice(it->price);

↓

// 値段の高い順に表示する
for (list<Product>::reverse_iterator it = products.rbegin(); ... )

「名前付き引数」コメント

Pythonなど、名前付き引数をサポートしている言語の場合、以下のように書くことができる。

Connect(timeout = 10, use_encryption = False)

名前付き引数をサポートしていない言語では以下のように書くことで、引数の名前を示すことができる。

Connect(/* timeout = */ 10, /* use_encryption = */ false);

全ての関数に名前付き引数コメントを使用する必要は無いが、よくわからない引数には使ったほうがよい。

情報密度の高い言葉を使う

// このクラスには大量のメンバがある。同じ情報はデータベースにも保管されている。ただし、
// 速度の面からここにも保管しておく。このクラスを読み込むときには、メンバが存在してい
// るかどうかを先に確認する。もし存在していれば、そのまま返す。存在しなければ、データベー
// スから読み込んで、次回のためにデータをフィールドに保管する。
↓
// このクラスの役割は、データベースのキャッシュ層である。