A word about naming things

I keep renaming things. A card becomes a tile, then a panel, then back to a card. Each time I tell myself it's a small decision, and each time it isn't. A name is the first thing a future reader sees, and it sets expectations before they open a single file.

Most of my renames happen for the same reason. I never wrote down what the thing was for. I reached for a label while the purpose was still fuzzy, so the label shifted with my mood that afternoon.

One sentence before the code

These days I write the purpose in one sentence before I open the editor. For a component that shows recent orders, it might be: "Shows a user's last three orders so they can reorder quickly." If that sentence needs the word "and," the component is probably doing two jobs. The name will split in two the moment I try to write it down.

The sentence also gives me something to check the implementation against. A reviewer can read the purpose, open the file, and see whether the code does what the sentence promises, without reconstructing intent from the props.

// Purpose: show the last three orders so the user can reorder quickly.
// If this grows a second job (e.g. billing history), split it.
export function RecentOrders({ orders }: { orders: Order[] }) {
  return <OrderList items={orders.slice(0, 3)} action="reorder" />;
}

// Purpose: show the last three orders so the user can reorder quickly.
// If this grows a second job (e.g. billing history), split it.
export function RecentOrders({ orders }: { orders: Order[] }) {
  return <OrderList items={orders.slice(0, 3)} action="reorder" />;
}

// Purpose: show the last three orders so the user can reorder quickly.
// If this grows a second job (e.g. billing history), split it.
export function RecentOrders({ orders }: { orders: Order[] }) {
  return <OrderList items={orders.slice(0, 3)} action="reorder" />;
}

Where it breaks down

I don't think this is a universal rule. Some things resist a clean sentence, especially utilities that exist to be composed. Forcing a purpose onto them produces a vague description like "helps with layout," which tells nobody anything.

I also notice I over-name when I'm tired. That usually means I'm avoiding the harder question of whether the component should exist at all. A good name for a bad component is still a bad component.

What I'm still unsure about

I can't tell yet whether this is a real principle or a habit that happened to work on a few projects. The real test is the next deadline, when I'm short on time and tempted to skip the sentence. If I still write it then, I'll trust it more. Ask me again after that.