Help us understand the problem. What is going on with this article?

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

この文書は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()) { ... }
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした