naming
Installation
SKILL.md
Naming
A name is a contract. Readers — above all diff reviewers, who see the call site but not the implementation — act on the name alone. A misleading name causes misuse; a vague name adds cognitive load (principle of least astonishment: code should do what its name makes you expect).
Flag, in order of severity:
- Misleading names (worst offense): the reader's natural assumption would be wrong.
Every caller now believes injection attacks are handled. Likewise afunction sanitizeInput(s: string) { return s.trim(); }get...that mutates, or acreate...implying checks it doesn't do. Rename to what it really does (trimWhitespace) — or better, make the code honor the name's claim. - Abbreviations and single letters:
usrCnt,procDt(d). The reader must reverse-engineer your compression scheme. WriteuserCount,processDate(date)— autocomplete pays the typing cost, not you. (Idiomatic loop indices likeiin a 3-line loop are fine.) - Types encoded in names: Hungarian notation (
strName),I-prefixed interfaces (unless the ecosystem convention, e.g. C#), andBase/Abstractin class names. Callers shouldn't care whether they hold an interface or a class. If the parent seems to need "Base" (BaseTruck), the child is under-specified: name the parentTruckand the childTrailerTruck. - Missing units:
delay— of what?delaySecondsat minimum; better, a unit-carrying type (Duration,TimeSpan) so the compiler makes the unit unmissable. - Names that need a translator: if a comment's main job is to define the name — "override" meaning the lifting of a billing freeze — the name failed; rename (
billingFreezeLiftRequested) so the comment can shrink or vanish. Watch for ceremony words —handle,process,resolve,manage,decide,-State,-Manager— which name plumbing instead of mechanism:manageAccountStatesays neither that it takes a row lock nor what the lock protects;lockAccountRowsays both. - utils/helpers/misc dumping grounds: a naming struggle usually means the code is in the wrong place. Move functions onto the types they operate on, or into cohesive modules that can be named (paging logic →
Paginator, cookie parsing →Cookie). Standard libraries have noutilsmodule for a reason.
Test every name: would a rushed reviewer, seeing only this name in a diff, make correct assumptions about its behavior, side effects, and ownership?