القائمة
Use when naming or renaming a Rust function, method, struct, enum, trait, or module — especially when a name is heading past three words (ensure_capture_device_present, load_and_apply_config), contains and/or/with/if_missing, or describes several steps at once.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when writing Rust that branches on an enum modeling state — a capture pipeline state, a Rotation/Flip mode, or any state-machine variant — to choose behavior or a value, or when adding a variant to such an enum. Also when reaching for an if-let chain, a let-else, matches!, or a `_` wildcard arm to consume an enum you own.
Use when composing or chaining Rust Result values — sequencing multi-step fallible operations, tempted by unwrap()/expect()/panic! on an expected failure, matching a Result mid-pipeline just to rewrap it in Ok/Err, discarding a Result with let _ = ..., or deciding where a Result finally becomes a process exit code or a rendered UI error.
Use when writing or modifying a Rust function with conditional branches — about to nest an if inside an if, write an else after a branch that returns/continues/breaks, thread a `let mut result` through branches to return at the end, or wrap a loop body in a condition.
Use when converting between numeric types in Rust, converting string↔number, or about to write `as` — `x as u32`, usize↔u32 index/pixel math, f64→u32 frame-dimension math, or formatting a value into a String.
Use when authoring or converting Rust types in this webcam-to-Syphon/Spout tool — defining a struct, enum, or function signature for capture devices, frames, rotation/crop/scale options, or pipeline state; typing several correlated fields as Option<T>; or about to reach for String, serde_json::Value, HashMap<String, String>, an over-permissive Vec<u8>, an `as` cast, or unwrap()/expect() to avoid modeling a value.
Use when branching on the prefix of a string with starts_with/strip_prefix (namespaced families like device URI schemes "avf://", "syphon://" or CLI transform tokens "rotate=", "flip=") and the branch count keeps growing, when a starts_with if-chain is 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 Rust function, method, struct, enum, trait, or module — especially when a name is heading past three words (ensure_capture_device_present, load_and_apply_config), contains and/or/with/if_missing, or describes several steps at once. |
Functions, methods, structs, enums, traits, and modules 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_capture_device_present = 4 ❌._bgr, _px, prepositions like _to_, _from_. crop_frame_to_roi = 4 ❌.sha256 = 1, bgra8 = 1).new, from_x, with_x) count normally but rarely trip the limit.#[test] functions (names narrate behavior), constants (DEFAULT_MASK_DILATE_PX is fine), local variables, trait method implementations (the trait fixed the name), and derive/trait-mandated names (fmt, from, try_from).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 type's) name, not each function's. Callers read capture_device::ensure(...) or frame.rotate(...) — the context words are written once.
// ❌ 4 words — ensure + locate + copy + verify crammed into one name
fn ensure_capture_device_present(name: &str, fallback: &str) -> Device { .. }
fn verify_capture_device_format(dev: &Device, want: PixelFormat) -> bool { .. }
// ✅ remedy 2 — module capture_device carries the noun phrase
mod capture_device {
fn ensure(name: &str, fallback: &str) -> Device { .. } // capture_device::ensure(...)
fn verify_format(dev: &Device, want: PixelFormat) -> bool { .. } // capture_device::verify_format(...)
}
// ✅ remedy 1 — or split by responsibility where a module isn't warranted
fn open_fallback_device(fallback: &str) -> Device { .. }
fn ensure_device(name: &str, fallback: &str) -> Device { .. } // outcome, not step list
The same move works with a struct as the namespace: CaptureDevice::ensure(), FrameBuffer::flush(), or a method on the value itself: frame.rotate(angle).
Rust convention pushes this further: don't repeat the module or type name inside the function — frame::rotate_frame ❌ → frame::rotate ✅. That repetition is remedy 2 done halfway; clippy's module_name_repetitions lint catches the type-name version of the same mistake.
| Smell in the name | What it reveals | Fix |
|---|---|---|
_and_ (open_and_configure_device) | two responsibilities | split: open_device + configure_device, compose at the caller |
_with_ / _by_ tail (filter_frames_by_size_and_format) | parameters leaking into the name | criteria are arguments: filter_frames(min_px, format) |
_if_missing / _if_needed | a guard clause fused into the verb | ensure_ already implies conditional: ensure_device |
repeated noun phrase across functions (capture_device_*) | a missing module/type | namespace it (capture_device::*); each function keeps its verb |
step-list verb chain (decode_rotate_encode) | orchestration named by its steps | name the outcome (transcode_frame); steps become their own functions |
| Mistake | Fix |
|---|---|
Abbreviating to sneak under the limit (ens_cap_dev_present) | Still multiple 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. crop_frame_to_roi → put the ROI in the type, split the step, or namespace it. |
Renaming without re-scoping (ensure_capture_device_present → ensure_capture) | Now the name lies — it no longer promises presence. Split first, then name what's left. |
| Applying the limit to tests, constants, or trait impls | Test names narrate behavior; constants encode ranges; trait-mandated names (fmt, from, try_from) aren't yours to shorten. All exempt. |
_ segment (or 4th capitalized word in CamelCase) → stop, split or namespace._and_, _with_, _if_ inside a function name → the scope is too broad.frame::rotate_frame) → clippy's module_name_repetitions is about to fire; drop the repeat.