コード品質 レッスン2
命名と可読性
変数・関数・クラスの命名がコードの可読性に与える影響と、良い名前を選ぶための指針を学ぶ
名前はコードの一番のドキュメント
コメントを書かなくても、名前そのものが意図を語るのが理想です。 良い名前は「これは何のためのものか」「何をするものか」を読み手に瞬時に伝えます。 逆に悪い名前は、読むたびに実装を追いかけて意味を推測する手間を発生させます。
// 悪い例: 何のデータか、何をする関数か分からない
function calc(d, x) {
return d.filter(i => i.s === x).length;
}
// 良い例: 名前だけで意図が読み取れる
function countOrdersByStatus(orders, status) {
return orders.filter(order => order.status === status).length;
}良い名前をつけるための指針
1. 意図を明確にする
dやtmpのような汎用的な名前は避け、 何のための値かを名前に反映させます。
2. 型・種類を暗示する語を使う
真偽値にはisActiveやhasPermissionのように is/has/can から始める。配列やコレクションには複数形を使う。
3. 対称性を保つ
open/close、start/stopのように、 対になる操作は対になる語彙で命名し、探しやすくする。
4. スコープに応じた長さにする
ループカウンタのような狭いスコープの変数は短くてもよいが、 広いスコープで使う変数・関数ほど具体的で長い名前が望ましい。
可読性を高めるその他の工夫
命名だけでなく、コードの構造そのものも可読性に大きく影響します。
// 悪い例: ネストが深く、条件の意図が読みにくい
function getDiscount(user) {
if (user) {
if (user.isPremium) {
if (user.orderCount > 10) {
return 0.2;
} else {
return 0.1;
}
}
}
return 0;
}
// 良い例: 早期returnでネストを浅くし、条件に名前をつける
function getDiscount(user) {
if (!user) return 0;
if (!user.isPremium) return 0;
const isLoyalCustomer = user.orderCount > 10;
return isLoyalCustomer ? 0.2 : 0.1;
}早期returnでネストを減らし、 条件式に意味のある変数名（isLoyalCustomer）をつけることで、 コメントがなくても意図が伝わるコードになります。
コメントとの使い分け
コメントは「何をしているか」ではなく「なぜそうしているか」を書くのが基本です。 「何をしているか」はコードそのものと良い命名で語らせましょう。
避けたいコメント
// iを1増やす
i++;意味のあるコメント
// 外部APIの仕様上、リトライ回数は
// 3回までに制限する必要がある
const MAX_RETRY = 3;ポイント
- • 名前は「見ただけで意図が分かる」ことを最優先にする
- • 真偽値はis/has/canで始め、コレクションは複数形にする
- • 早期returnでネストを浅くし、条件に名前をつける
- • コメントは「何を」ではなく「なぜ」を書く
確認クイズ
1 / 3変数名 `d` や `tmp` のような汎用的な名前が問題視される理由はどれか？