Naming Things Skill

Naming Anti-Patterns

Before & After Examples

Example 1: Order Processing

# BEFORE: generic names, no intent
def process(d):
    tmp = []
    for x in d:
        if x['amt'] > 0:
            tmp.append({'id': x['id'], 'total': x['amt'] * x['qty']})
    return tmp

# AFTER: names reveal role and intent
def calculate_order_totals(orders):
    completed_orders = []
    for order in orders:
        if order['amount'] > 0:
            completed_orders.append({
                'order_id': order['order_id'],
                'total': order['amount'] * order['quantity']
            })
    return completed_orders

Example 2: React Component

// BEFORE: generic state, vague handler
function UserProfile({ info }: { info: any }) {
  const [data, setData] = useState<any>(null)
  const [flag, setFlag] = useState(false)
  function handle() {
    if (flag) { setFlag(false); sendEmail(data.email) }
    setFlag(true)
  }
  return <div onClick={handle}>{data?.name}</div>
}

// AFTER: descriptive names reveal intent
function UserProfile({ userInfo }: { userInfo: UserInfo }) {
  const [profile, setProfile] = useState<UserProfile | null>(null)
  const [isEmailSent, setIsEmailSent] = useState(false)
  function handleClick() {
    if (isEmailSent) { setIsEmailSent(false); sendEmail(profile.email) }
    setIsEmailSent(true)
  }
  return <div onClick={handleClick}>{profile?.name}</div>
}

Step-by-Step Workflow

Step 1: Identify What You're Naming

Classify the target: variable, function, class, module, parameter, or constant.

Step 2: Determine Its Role

Name the role: motivation, responsibility, distinguishing behavior, collaborators, and reading context.

If the role is unclear, consider redesigning before renaming.

Step 3: Check Against Language Culture

Each language ecosystem has established conventions. Consult the reference for the target language in references/<language>.md.

Step 4: Check Project & Domain Consistency

• Project glossary: Does the project already have a term for this concept? Use it.
• Domain language: Would a domain expert (user, product manager) use this name?
• Pair with existing code: How does the rest of the codebase name similar things? Match that pattern.

If there's no glossary, suggest starting one (even informally).

Step 5: Suggest the Name

Apply the principles:

1. Be specific — buyer > user, applyDiscount > deductPercent
2. Be truthful — name must accurately describe what the thing is or does
3. Be pronounceable — can you discuss it aloud in a code review?
4. Be searchable — avoid names so common they swamp search results
5. Be scannable — put the most important/unique part of the name first

Function naming guide:

Step 6: Validate the Rename

After suggesting/proposing a rename:

1. Read the code aloud with the new name — does it still make sense? Can you discuss it in a code review?
2. Check for conflicts — does the new name shadow anything or clash with an existing symbol?
3. Verify grep-ability — will you find all usages of this name? (Avoid names so short or common they're unsearchable.)
4. Consider the new team member test — would someone new to the codebase understand it immediately?

Step 7: Execute the Rename

1. Use IDE refactoring tools (rename symbol, not find-and-replace) to catch all references
2. Run tests after renaming to verify nothing broke
3. Grep for stale references (comments, docs, config files that might reference the old name)
4. Fix related names in the vicinity — if you renamed getData to fetchOrders, are there other get* methods nearby that should follow the same pattern?
5. If blocked (public API, compatibility), add a deprecation notice and schedule the rename