Naming readability

Naming Readability

名前は「実装を見ずに用途が推測できるか」を基準に選ぶ。スコープが短いほど短い名前でよく、広く使われるほど説明的にする。

鉄則

1. 命名に迷ったら「この名前だけを見た第三者が、実装を見ずに正しく用途を推測できるか」を判断基準にする。
2. 変数名の情報量はスコープ・生存期間に比例させる。数行で完結するループカウンタに長い名前は不要。モジュール全体・公開APIで使われる名前は省略しない。
3. 同じ概念には同じ語彙を必ず統一する（getUserとgetUserInfoのような揺れを作らない）。
4. コメントは「何をしているか（what）」ではなく「なぜそうしているか（why）」を書く。コードを読めば分かることは書かない。

作業手順

ステップ1: 変数を命名する

1. スコープを確認する（数行内で完結するか、関数全体か、モジュール・公開APIか）。
2. スコープが狭いほど短く（i, jはループ内のみ許容）、スコープが広いほど説明的にする。
3. 発音可能・検索可能な名前にする（eではなくelapsedTimeInDaysのように）。
4. 所属先オブジェクトから自明な文脈は名前から省く（Car.carColorではなくCar.color）。
5. 略語・省略形は、そのドメインで広く通じるもの（id, url, http等）以外は避ける。

ステップ2: 関数を命名する

1. 動詞（＋目的語）で始め、「何をして何を返すか」が名前だけで推測できるようにする（例: fetchUserById, isValidEmail）。
2. 真偽値を返す関数はis/has/can等のプレフィックスを付ける。
3. 真偽値フラグを引数に取る関数（例: createFile(name, isTemp)）は分岐ごとに関数を分割する（createFileとcreateTempFile）。
4. 同じ概念を表す動詞をプロジェクト全体で統一する（fetch/get/retrieveを混在させない）。

ステップ3: 関数の大きさを判定し、必要なら分割する

1. スクロールしないと全体が見えない関数は分割候補（Long Method）。
2. 関数が単一責任か確認する。複数の関心事（入力検証・ビジネスロジック・出力整形等）が混ざっていたら、それぞれをExtract Functionで独立させる。
3. 引数は2個以下を目安にする。3個以上必要ならオブジェクト（Parameter Object）にまとめる。
4. 分割後、それぞれの関数が「名前だけで内容を説明できる」ことを確認する。名前が説明的すぎて長くなる場合は責務がまだ混ざっている兆候。

ステップ4: コメントを書く

1. コードを読めば分かる内容（whatの説明）は書かない。
2. 「なぜこの実装を選んだか」「なぜ一見不要に見えるこの処理が必要か」（whyの説明）を書く。
3. TODOコメントは対応者・チケット番号等、後で追跡可能な情報を含める。
4. 公開関数・APIには入出力の契約（前提条件・返り値・例外条件）を簡潔に書く。

チェックリスト

• 変数名はスコープに応じた情報量になっているか（短命=短く、広域=説明的に）
• 同じ概念に異なる語彙を使っていないか（get/fetch/retrieveの混在等）
• 関数名は動詞から始まり、何をして何を返すか名前だけで分かるか
• 真偽値フラグ引数で分岐する関数になっていないか
• 引数は2個以下か、3個以上ならオブジェクトにまとめたか
• 関数はスクロールなしで全体が見渡せる大きさか
• 単一責任か（クラス・関数の変更理由が1つに限定されているか）
• コメントはwhatではなくwhyを説明しているか

アンチパターン集

やりがちな命名・実装	現実・対処
data, info, temp, flagのような汎用名	用途が実装を読まないと分からない。ドメイン用語で具体的に命名する
ループカウンタにindexOfCurrentlyProcessingItemInTheListのような長い名前	スコープが狭いのに情報量過多。iで十分な文脈もある
getUserとgetUserInfoとfetchUserDataが同居	概念の揺れがコードベース全体の検索性・一貫性を壊す。語彙を統一する
process(data, true, false)のような真偽値フラグの羅列	呼び出し側で意味が読めない。フラグごとに関数を分けるか、名前付き引数にする
コメントで「iを1増やす」のようにコードの直訳を書く	情報量ゼロ。書くなら「なぜこの値だけ+1するのか」というwhyを書く
1つの関数に検証・計算・保存・通知を全部詰め込む	単一責任違反。名前が「〜と〜と〜をする」の羅列になったら分割サイン
略語を独自ルールで作る（usrCfgTmp等）	ドメインで通じない略語は可読性を下げる。フルスペルか、広く通じる略語のみ使う

出典

• Brian Kernighan（K&Rスタイル）の一般化 — Code Simplicity: Readability and Naming Things
• ryanmcdermott/clean-code-javascript（MIT License）— 関数設計チェックリスト、命名規則、SOLID原則