meaningful-names

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Meaningful Names

Names are the first documentation a reader meets. A good name is a tiny, always-accurate comment baked into the identifier itself. This file covers how to name variables, functions, types, and components so a wizard reading your code six months from now understands intent without deciphering anything.

For how these names get used inside functions, see [functions](../functions/SKILL.md).

## Quick Reference

| Principle | Bad | Good |
| --- | --- | --- |
| Intention-revealing | `d` | `daysSinceLastQuidditchMatch` |
| Honest, no disinformation | `spellList` (a `Map`) | `spellsById` |
| Meaningful distinction | `house1`, `houseData`, `houseInfo` | `sourceHouse`, `targetHouse` |
| Pronounceable | `slytStdntCnt` | `slytherinStudentCount` |
| Searchable | `7` | `MAX_QUIDDITCH_PLAYERS` |
| No type encoding | `strSpellName`, `IWizard` | `spellName`, `Wizard` |
| Clarity over brevity | `castW(w, s)` | `castSpell(wizard, spell)` |
| Booleans read as questions | `enrolled`, `wand` | `isEnrolled`, `hasWand` |

## Use Intention-Revealing Names

A name must answer three questions on its own: **why does this thing exist, what does it do, and how is it used**. If you need a trailing comment to explain a name, the name has already failed. Replace it with one that carries the explanation.

```ts
// Bad — what is `d`? What is `7`? What is this list actually holding?
const d = 12
const list: number[] = []
for (const x of houses) {
  if (x[3] === 7) list.push(x)
}
```

```ts
// Good — the names ARE the comment
const daysSinceLastQuidditchMatch = 12

const MAX_QUIDDITCH_PLAYERS = 7 as const

const fullQuidditchTeams = houses.filter(
  (house) => house.playerCount === MAX_QUIDDITCH_PLAYERS,
)
```

The second version needs no comment because every name states its own purpose. You can read it aloud and it sounds like a sentence about the domain.

## Avoid Disinformation — Make Names Honest

A name must never promise something that is false. Disinformation is worse than a vague name because a vague name makes you check, while a lying name makes you *trust*. The classic trap is naming a collection after a type it is not: calling a `Map` a `List`, or calling a flat array a `Group`.

```ts
// Bad — `spellList` is a Map, and `houseGroup` is a single house, not a grouping
const spellList: Map<string, Spell> = new Map()
const houseGroup: House = getHouseByName('gryffindor')
```

```ts
// Good — names match reality
const spellsById: Map<string, Spell> = new Map()
const gryffindor: House = getHouseByName('gryffindor')
```

Reserve words like `List`, `Map`, `Set`, `Group`, `Queue` for when the value actually is that shape. When a reader sees `spellsByHouse: Map<House, Spell[]>`, the name and the type agree — that agreement is trust you never want to break.

## Make Meaningful Distinctions

When two names differ only by a number series or a noise word, the reader cannot tell which one to use. `house1` and `house2` say nothing about their roles. `houseData` and `houseInfo` are the same word dressed twice — `Data` and `Info` add zero information. Distinguish names by their *role in the domain*.

```ts
// Bad — which house is which? What makes `Info` different from `Data`?
const transferPoints = (house1: House, house2: House, points: number) => {
  house1.points -= points
  house2.points += points
}

const houseData = fetchHouse('slytherin')
const houseInfo = fetchHouse('hufflepuff')
```

```ts
// Good — names encode the role each argument plays
const transferPoints = (sourceHouse: House, targetHouse: House, points: number) => {
  sourceHouse.points -= points
  targetHouse.points += points
}

const attackingHouse = fetchHouse('slytherin')
const defendingHouse = fetchHouse('hufflepuff')
```

Now nobody can accidentally swap the arguments — the names refuse to be confused.

## Use Pronounceable, Human-Language Names

Code is read by humans far more often than it is written. If you cannot say a name out loud in a code review without spelling it letter by letter, it is too compressed. Vowel-dropping and cryptic abbreviations save a few keystrokes and cost every future reader real effort.

```ts
// Bad — unpronounceable; try saying `slytStdntCnt` in a standup
type HgwrtsRcrd = {
  slytStdntCnt: number
  genYmdhms: string
  wndCoreTyp: string
}
```

```ts
// Good — reads like language
type HogwartsRecord = {
  slytherinStudentCount: number
  generationTimestamp: string
  wandCoreType: string
}
```

If a name is a real word, people can talk about it, search for it, and remember it. Abbreviate only when the abbreviation is more standard than the full form (`url`, `id`, `html`).

## Use Searchable Names

A bare number or single letter scattered through the code is impossible to grep and impossible to change safely. `7` might mean the max Quidditch players, the number of Horcruxes, or the day of the week — the reader cannot tell, and you cannot search for "the max-players 7" specifically. Give any meaningful value a named constant.

From hzblj/skills, MIT.

More from hzblj/skills