القائمة
Use when naming or renaming a Python function, method, or class — especially when a name is heading past three words (ensure_model_file_present, load_and_validate_config), contains and/or/with/if_missing, or describes several steps at once.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when writing or modifying a Python function with conditional branches — about to nest an if inside an if, write an else after a branch that returns/raises/continues, or assign a result variable in branches to return at the end.
Use when writing Python that branches on a value carrying a modeled state — a union of dataclass variants, a Literal-tagged kind/status/type field, or any state-machine state — to choose behavior or a return value, or when adding a variant to such a union. Also when reaching for an if/elif or isinstance chain on a tag field, a hand-rolled exhaustiveness helper, or a dict lookup to consume a tagged union.
Use when composing or chaining dry-python returns Result / FutureResult values — sequencing multi-step operations where each step can fail, recovering from a specific error, or deciding where a Result becomes a plain value, exit code, or response. Also when reaching for .unwrap(), .failure(), ._inner_value, isinstance(r, Success) / is_successful() mid-pipeline, match on Success/Failure outside the consumption edge, Result.do, or try/except around Result-returning code.
Use when converting a value to int, float, str, or bool in Python — about to write int(x), float(x), str(x), bool(x), a bare `if x:` / `x or default` on a value where None, 0, or "" mean different things, or filter(None, xs).
Use when authoring or converting Python type annotations — defining a class / TypedDict / pydantic model / function signature, typing arguments or state, deciding between optional (None / NotRequired) fields and a union, or about to reach for Any, dict[str, Any], cast(), or a type-ignore comment. The minimum modeling rules for typed Python under pyright.
Use when branching off the prefix of a string with str.startswith (namespaced name families like "file.", "edit.", "edit.image.") and the number of prefix branches is growing, when a startswith if-chain is becoming hard to test or extend per-family, or when adding several new prefix families to an existing dispatcher.
| name | three-word-naming |
| description | Use when naming or renaming a Python function, method, or class — especially when a name is heading past three words (ensure_model_file_present, load_and_validate_config), contains and/or/with/if_missing, or describes several steps at once. |
Functions, methods, and classes get at most three words. A name that needs a fourth word is not a naming problem — it is a scope problem: the code is doing more than one thing, or it is missing the namespace that should carry part of the name. Fix the scope, and the short name falls out.
Never fix a too-long name by abbreviating, dropping vowels, or fusing words. Shorten the responsibility, not the spelling.
_, CamelCase on capitals: read_frame_bgr = 3, LoadedFaceModel = 3, ensure_model_file_present = 4 ❌._bgr, _px, prepositions like _to_, _from_. mask_to_polygon_px = 4 ❌._ (private) and dunders don't count. An acronym or digit group is one word (sha256 = 1).DEFAULT_MASK_DILATE_PX is fine), local variables.1. Raise the abstraction — split and compose. A 4+ word name is usually a step list. Each step gets its own ≤3-word function; the composition point keeps a short name describing the outcome, not the steps.
2. Move a word into a namespace. If the extra words are a noun phrase repeated across the module, they are the module's (or class's) name, not each function's. Callers read model_file.ensure(...) — the context words are written once.
# ❌ 4 words — "ensure" + locate + copy + verify crammed into one name
def ensure_model_file_present(model_path, fallback_dir): ...
def verify_model_file_digest(model_path, expected): ...
# ✅ remedy 2 — module model_file.py carries the noun phrase
def ensure(model_path, fallback_dir): ... # model_file.ensure(...)
def verify_digest(model_path, expected): ... # model_file.verify_digest(...)
# ✅ remedy 1 — or split by responsibility where the module isn't warranted
def copy_from_fallback(model_path, fallback_dir): ...
def ensure_model(model_path, fallback_dir): ... # outcome, not step list
The same move works with a class as the namespace: ModelFile.ensure(), EmbeddingCache.refresh().
| Smell in the name | What it reveals | Fix |
|---|---|---|
_and_ (load_and_validate_config) | two responsibilities | split: load_config + validate_config, compose at the caller |
_with_ / _by_ tail (filter_faces_by_score_and_size) | parameters leaking into the name | the criteria are arguments: filter_faces(min_score=, min_px=) |
_if_missing / _if_needed | a guard clause fused into the verb | ensure_ prefix already means conditionally: ensure_model |
repeated noun phrase across functions (model_file_*) | a missing module/class | namespace it; each function keeps the verb |
step-list verb chain (download_verify_load) | orchestration named by its steps | name the outcome (load_model); steps become their own functions |
| Mistake | Fix |
|---|---|
Abbreviating to sneak under the limit (ens_mdl_file_present) | Still 4 responsibilities. Split or namespace — never compress spelling. |
Vague 1-worder to dodge the limit (process, handle, do_it) | Under-specific is as bad as over-long. Three precise words beat one vague one. |
Counting _bgr/_px as "free" suffixes | They count. mask_to_polygon_px → put the unit in the type or docstring, or namespace the conversion. |
Renaming without re-scoping (ensure_model_file_present → ensure_file) | Now the name lies. First split the responsibilities, then name what's left. |
| Applying the limit to tests/constants | Test names narrate behavior; constants encode ranges. Both are exempt. |
_ segment → stop typing, split or namespace._and_, _with_, _if_ inside a function name → the scope is too broad.