# Naming As Design

> Use when code feels tangled or needs a comment to explain what something is, when reaching for a name and nothing fits, or when a name is vague (data, tmp, handle, process, manager, util, doStuff) and the fuzziness hides a fuzzy design

- Skill: `atgreen/naming-as-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atgreen/naming-as-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atgreen/naming-as-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: atgreen (https://skillmd.com/u/atgreen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/atgreen/naming-as-design

---


# Naming-as-Design

## Overview

**Core principle:** Naming is not decoration applied after the design — naming *is* the design.
A thing you can't name cleanly is usually a thing that isn't cleanly *one thing*. Use the struggle
to name as a signal about the structure, and renaming as a tool to fix it.

When the right name is obvious, the design underneath is sound. When no name fits, the name isn't
the problem — the shape is.

## The Diagnostic

A hard-to-name thing is telling you something. Read the signal:

| Naming symptom | What it usually means | The fix |
|---|---|---|
| The name needs "and" (`parseAndValidate`) | It does two things | Split it into two named things |
| Only a vague name fits (`data`, `manager`, `process`) | Its responsibility is vague | Sharpen the responsibility, then name it |
| The name lies about what it does now | Behavior drifted from intent | Rename to the truth, or restore the intent |
| You reach for a comment to say what it *is* | The name is underperforming | Move the comment's content *into* the name |
| Same concept, three different names across the file | You haven't decided what it is | Pick one true name, use it everywhere |

## The Practice

1. **Name for the reader, from the outside.** A name describes what a thing *is* or *returns*,
   in the caller's vocabulary — not how it's implemented inside. `activeUsers`, not `filteredList`.
2. **Make the name carry the weight a comment would.** `secondsUntilExpiry` needs no comment;
   `t` plus a comment does the same job worse. Every comment explaining a name is a naming bug.
3. **Let a failure to name change the code, not just the label.** If nothing fits, don't force a
   bad name — split, merge, or reshape until a good name becomes available. The name comes *last*
   because it's the design's signature.
4. **One concept, one name; one name, one concept.** Synonyms drifting across a codebase
   (`fetch`/`get`/`load`/`retrieve` for the same act) make readers hunt for distinctions that
   aren't there. Consistency is kindness.

## Quick Reference

| Weak name | Why it's weak | Stronger |
|---|---|---|
| `data`, `info`, `obj` | Says nothing | `invoice`, `userProfile` |
| `tmp`, `x`, `result` | No meaning | `remainder`, `parsedDate` |
| `handle`, `process`, `doIt` | Verb without object | `retryFailedJobs`, `renderInvoice` |
| `manager`, `helper`, `util` | Junk-drawer | Name the actual job it does |
| `flag`, `check`, `isValid` | Which flag? valid how? | `hasUnsavedChanges`, `isPastDue` |
| `getData()` returning a filtered subset | Hides the filter | `getActiveUsers()` |

## Common Mistakes

- **Naming by implementation, not by meaning.** `sortedList` breaks the day you switch to a set;
  `rankedCandidates` survives. Name the *what*, not the *how*.
- **Renaming the label without re-reading the passage.** A name is only better if the code around
  it reads better. Names live in sentences; read the sentence.
- **Encoding types into names** (`strName`, `listUsers`) when the language already tracks types.
  The name should add meaning the type can't.
- **Accepting a bad name because "it's just a local."** Locals are where the reader spends the
  most time. They deserve the most care, not the least.

## Relationship to Other Skills

This is the **whittler**'s second pass, after **subtraction-first** (a good name often deletes a
comment or a helper). Renaming for the reader flows directly into **reading-like-prose**.