0
Help us understand the problem. What are the problem?

More than 1 year has passed since last update.

posted at

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

この文書は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()) { ... }

Register as a new user and use Qiita more conveniently

  1. You can follow users and tags
  2. you can stock useful information
  3. You can make editorial suggestions for articles
What you can do with signing up
0
Help us understand the problem. What are the problem?