Quartz 5

How to Name Things

Properties1
tagsnaming, software-design, clean-code, communication, pragmatic-programming

4 min read

Summary

Koleman Nix argues that naming in software is fundamentally an act of communication, not a mechanical craving for consistency — every name (variable, function, column, endpoint) transmits meaning to colleagues, your future self, and now LLMs. He works through concrete cases (a created_at timestamp column, an optional variable, a unit-converting function) to show that a good name requires understanding what a thing actually means in context, not applying a rule reflexively.

Koleman Nix 主張，軟體中的命名本質上是一種溝通行為，而非機械式地追求一致性——每一個名稱（變數、函式、欄位、端點）都在向同事、未來的自己，以及現在的語言模型傳遞意義。他透過具體案例（created_at 時間戳記欄位、一個 optional 變數、一個做單位轉換的函式）說明：好的命名需要理解該事物在情境中的真正意涵，而不是機械套用規則。

Key Points

  • Naming touches nearly every layer of a system: local variables, functions, struct fields, API endpoints, application pages, database tables/columns, even the product name — each is a communication act
  • Consistency-for-its-own-sake is a misconception; a name should be driven by what the thing means, taking in as much context as possible, not just its type or current narrow usage
  • Database column example: created_at is a good default for a timestamp marking when something began to exist (at = preposition of time); created_on fits better when the column is a date, not a timestamp — the right call depends on what the row/column represents
  • Function naming example: a function converting reals to integral pixels shouldn’t try to encode every specific call-site narrative in its own name — that story belongs in the local variable names at the call site, not the function signature
  • DRY, properly understood, means a fact should live in exactly one place, and two pieces of code expressing the same fact should point at that same place — naming discipline supports this
  • Hard cases (e.g. an “optional” variable) can’t be resolved by convention alone: “buckle up and engage deeply — read the code from the top, in your head, pretending to be your teammate. Then ruminate on this variable and its properties.” Is it always optional? Optional only because its absence is an error (which should maybe be handled earlier)? A fallback? A set of overrides? — the answer to why it’s optional should shape the name

Insights

The essay’s throughline is that naming is a proxy for thinking clarity — if you can’t name something well, you likely don’t yet understand it well enough. This reframes naming disputes (bikeshedding over data vs payload vs result) as a signal to dig into the domain semantics rather than a style preference to settle by convention. It also explicitly extends the audience for names beyond humans to LLMs — a name is now also a piece of context an AI coding agent reads to infer intent, raising the stakes on precision (a vague name degrades both human and AI comprehension of a codebase). The created_at/created_on distinction is a nice compact example of how a naming “rule” (always suffix timestamps with _at) breaks down once you consider what the column actually stores.

Connections

Raw Excerpt

The answer is to buckle up and engage deeply; to read the code from the top, in your head, pretending to be your teammate. Then ruminate on this variable and its properties. Is it always optional? Is it optional only because its absence is an error, in which case perhaps we should handle that error earlier, or name the variable in a way that says so? Is it a fallback? Is it a set of overrides?

Graph View

Backlinks