The reading room · Digna Legi
How to name things
/100
80–100: high value. 70–79: worth the time. Below 70: below the usual publication threshold.
Evidence-reviewed score based on available publisher text. The evidence is substantial and argument-dense; its value comes from experience and conceptual analysis rather than research support.
Scores reflect one reader’s profile, not an objective quality rating. Best is a separate personal selection.
How scoring works →This brief · about 3 min with detail
Why read this
Names are compressed explanations of system meaning, and choosing them can expose hidden ambiguities in data models and behavior.
AI brief · Checked against source text
The main idea
The author argues that names are compressed explanations of a system’s meaning, addressed to colleagues, future maintainers, and language models. Good naming works by forcing the author to distinguish essence from temporary need: whether a value is optional, when a document was created versus uploaded, or whether two equal constants express the same fact. The act of naming is therefore also model design.
Some background helpful. Familiarity with optional values, map operations, database migrations, and language-model-assisted programming.
Go a little deeper
Consistency is the wrong idol
The essay rejects consistency as a freestanding virtue. Naming every optional value the same way may feel orderly, but it can hide the reason for absence: error, fallback, override, or normal incompleteness. The author’s alternative is consistency of inquiry, not consistency of surface pattern: read the surrounding code, infer the concept’s role, and choose a name that transmits that understanding.
Names should follow essence, not use case
A name derived from the immediate task can trap a general operation inside a narrow story. The pixel-conversion example shows this: the function rounds a floating-point number to an integer, but its caller happens to use it for pixels. If the function is named after pixels, the caller’s context leaks into the function’s identity and obscures what the function actually does.
Optionality is a model decision
An optional map of configuration overrides represents absence twice: individual keys may be missing, and the map itself may be missing. The author asks whether those states actually mean different things. If a missing map means a parsing error, handle it explicitly; if it means the same as an empty map, simplify the model at the boundary.
Language models amplify naming quality
The author connects naming to model-assisted programming by arguing that language models depend heavily on the terms already present in a codebase. A clear, focused codebase lets the model extend a coherent intent; a codebase filled with approximate names and interpolated additions degrades the model’s context. Maintaining terminology becomes part of sustaining AI-assisted development.
A case from the article
The misleading document date
A document system has a field called documentDate. One screen treats it as the date written on the document, ingestion stores the arrival date, and a staleness rule checks it as if one meaning applied everywhere. The example shows how a vague name can become contradictory behavior, then harden into a risky database migration and backfill problem.
How the case is made
The case is made through software examples, database-field scenarios, and the author’s observations about codebases and language models.
A question to take away · from Digna Legi
Where in your system does a name feel merely awkward, but might actually be hiding two competing meanings?
What the original adds
The original adds several concrete naming contrasts: timestamp suffixes, optional fallback configuration shapes, accidental equality in constants, and a map-union function whose need-based name hides a standard operation.
About this brief
AI-written, then separately checked for source support, useful detail and clarity. The author’s claims and our editorial question are kept separate. The original remains the author’s work. How we select and summarise →
How was this brief?
Rate this summary, separately from the author’s article.
Optional. Saved in this browser; shared only if you allow analytics.
How was the original article?
Rate the author’s original after reading it.
Optional. Saved in this browser; shared only if you allow analytics.
Digna legi. Worth reading.