| name | code-naming |
| description | Naming decisions for variables, functions, classes, constants, and APIs. Use when choosing names, reviewing naming quality, refactoring unclear names, or establishing naming conventions. Covers descriptive naming, naming as documentation, language-specific conventions, and common naming antipatterns. |
Code Naming
The Naming Decision Table
| You're naming a... | It should read like... | Form | Examples |
|---|
| Class / Type | A noun or noun phrase | PascalCase (most langs) | UserProfile, HttpClient, InvoiceParser |
| Function / Method | A verb or verb phrase | camelCase or snake_case | validateEmail, send_invoice, calculateTotal |
| Boolean | A yes/no question | is/has/can/should prefix | isActive, hasPermission, canRetry |
| Collection | A plural noun | Plural form | users, pendingOrders, activeConnections |
| Constant | A named fact | UPPER_SNAKE_CASE (most langs) | MAX_RETRY_COUNT, DEFAULT_TIMEOUT_MS |
| Interface | A capability or contract | Language-specific | Serializable, IDisposable, Reader |
| Enum | A set of named options | PascalCase values | Color.Red, RetryPolicy.ALLOW_RETRY |
| Event / Callback | What happened or will happen | Past/present tense | onClick, onUserCreated, handleSubmit |
The Three Questions Test
Before committing to a name, verify it answers all three:
- What is it? — The name identifies what the thing represents
- What does it do? — For functions: the action is clear from the name alone
- What are the boundaries? — The name hints at scope, lifetime, or constraints
If a name requires a comment to be understood, the name is wrong.
Naming Antipatterns
Names That Lie
| Antipattern | Problem | Fix |
|---|
accountList when it's a Set | Wrong data structure in name | accounts (just use plural) |
processData_v2 | Version control in names | Use version control, not naming |
getUser() that also logs and caches | Name doesn't reveal side effects | fetchAndCacheUser() or split |
isEnabled that modifies state | Query name hides a command | Separate query from mutation |
Names That Don't Try
| Antipattern | Problem | Fix |
|---|
data, info, item, thing | Generic to the point of meaningless | Use domain-specific terms |
tmp, val, x beyond tiny scope | Forces reader to track mentally | currentTemperature, retryCount |
manager, handler, processor | Vague role descriptions | Describe what it manages |
utils, helpers, misc | Grab-bag namespaces | Group by domain or operation |
Names That Mislead
| Antipattern | Problem | Fix |
|---|
| Inconsistent casing | Readers assume variables are lowercase | Follow language conventions exactly |
Abbreviations (usrRepo, passwd) | Ambiguous unless universally known | Spell it out: userRepository, password |
Noise words (UserData vs UserInfo) | Indistinguishable without reading code | Pick one and be consistent |
Negated booleans (isNotActive) | Double negatives in conditions | Use positive: isActive |
Names That Over-Specify
| Antipattern | Problem | Fix |
|---|
Hungarian notation (strName, iCount) | Type system already encodes types | Just name, count |
Gratuitous prefix (GSDAccountService) | Every class in app has same prefix | Use namespaces/packages |
AbstractBase + Impl suffix | Naming the pattern not the concept | UserService + DefaultUserService |
Decision Checklist
