Naming readability
Skill goonobu-dot/dev-skills-library/skills/naming-readability
15 auto-selectable Claude Code skills distilling engineering best practices (Kent Beck, Fowler, Google SRE, OWASP, Anthropic, Netflix…), with a bilingual offline learning site. Make Claude Code write better code — and learn the practices yourself.
npx -y skills add goonobu-dot/dev-skills-library --skill naming-readabilityAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 29 days oldThe repository was created 29 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Naming and readability standards distilled from clean-code guides and style guides. Use when naming variables/functions/classes, splitting long functions, writing comments, or when the user says 命名, 読みやすく, わかりやすい名前. Not for module/class structure design (use deep-module-design).
SKILL.md
5.9 KB, as published. Nobody here has run it
Naming Readability
名前は「実装を見ずに用途が推測できるか」を基準に選ぶ。スコープが短いほど短い名前でよく、広く使われるほど説明的にする。
鉄則
- 命名に迷ったら「この名前だけを見た第三者が、実装を見ずに正しく用途を推測できるか」を判断基準にする。
- 変数名の情報量はスコープ・生存期間に比例させる。数行で完結するループカウンタに長い名前は不要。モジュール全体・公開APIで使われる名前は省略しない。
- 同じ概念には同じ語彙を必ず統一する（
getUserとgetUserInfoのような揺れを作らない）。 - コメントは「何をしているか（what）」ではなく「なぜそうしているか（why）」を書く。コードを読めば分かることは書かない。
作業手順
ステップ1: 変数を命名する
- スコープを確認する（数行内で完結するか、関数全体か、モジュール・公開APIか）。
- スコープが狭いほど短く（
i,jはループ内のみ許容）、スコープが広いほど説明的にする。 - 発音可能・検索可能な名前にする（
eではなくelapsedTimeInDaysのように）。 - 所属先オブジェクトから自明な文脈は名前から省く（
Car.carColorではなくCar.color）。 - 略語・省略形は、そのドメインで広く通じるもの（
id,url,http等）以外は避ける。
ステップ2: 関数を命名する
- 動詞（＋目的語）で始め、「何をして何を返すか」が名前だけで推測できるようにする（例:
fetchUserById,isValidEmail）。 - 真偽値を返す関数は
is/has/can等のプレフィックスを付ける。 - 真偽値フラグを引数に取る関数（例:
createFile(name, isTemp)）は分岐ごとに関数を分割する（createFileとcreateTempFile）。 - 同じ概念を表す動詞をプロジェクト全体で統一する（
fetch/get/retrieveを混在させない）。
ステップ3: 関数の大きさを判定し、必要なら分割する
- スクロールしないと全体が見えない関数は分割候補（Long Method）。
- 関数が単一責任か確認する。複数の関心事（入力検証・ビジネスロジック・出力整形等）が混ざっていたら、それぞれをExtract Functionで独立させる。
- 引数は2個以下を目安にする。3個以上必要ならオブジェクト（Parameter Object）にまとめる。
- 分割後、それぞれの関数が「名前だけで内容を説明できる」ことを確認する。名前が説明的すぎて長くなる場合は責務がまだ混ざっている兆候。
ステップ4: コメントを書く
- コードを読めば分かる内容（whatの説明）は書かない。
- 「なぜこの実装を選んだか」「なぜ一見不要に見えるこの処理が必要か」（whyの説明）を書く。
- TODOコメントは対応者・チケット番号等、後で追跡可能な情報を含める。
- 公開関数・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原則