コードヘルス - コメントをつけるべきか、つけないべきか

この文書はCode Health: To Comment or Not to Commentの翻訳です。

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

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

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

説明的な変数を使う。

よくない例

// 割引を価格から引く
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()) { ... }