コードを読んでいると、いいコメントほど助けになるものはない。 しかしながら、コメントは必ずしもいいものだとは限ない。 ときには、コメントが必要ということはそのコードがリファクタリングするべきとういサインかもしれない。

コード自体で説明できないときにだけコメントを使おう

コードが何をしているか説明するコメントが必要だと考えるなら、まず、次のどれかを試そう。

よくない例

// 割引を価格から引く
finalPrice = (numItems * itemPrice)
    - min(5, numItems) * itemPrice * 0.1;

修正後

price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

よくない例

// Filter offensive words.
for (String word : words) { ... }

修正後

filterOffensiveWords(words);

よくない例

int width = ...; // Width in pixels.

修正後

int widthInPixels = ...;

よくない例

// heightは常に0より大きいので大丈夫
return width / height;

修正後

checkArgument(height > 0);
return width / height;

コメントが役に立つ場合

なぜコードがそうなっているのか（そうなっていないのか）を説明する

// 計算コストが高いため一度だけ計算する

// Fooはスレッド安全でないため、新たなFooを作る

// 順序に注意。なぜなら、

@SuppressWarnings("unchecked") // このキャストは安全。なぜなら、

よくない例

// Get all users.
userService.getAllUsers();

よくない例

// Check if the name is empty.
if (name.isEmpty()) { ... }