Naming
Choosing identifiers so the code states its own meaning without commentary.
Naming is the primary documentation mechanism in code. An identifier is read far more often than it is written, appears at every call site, and — unlike a Code Comment — cannot drift away from the thing it names.
Good names are usually a matter of naming the contract rather than the implementation. A function called rewriteContent promises that structure is preserved and only copy changes; one called regenerateSection promises nothing in particular, so callers guess. Renaming the first to the second is a genuine bug fix, because the wrong name licensed the wrong assumption. The deliberate exception is the Metasyntactic Variable — foo, bar, baz — a placeholder chosen to state nothing at all, because an example about structure is spoiled by an identifier that smuggles a domain into it.
Names also carry scope information. A name that is accurate but too general invites use outside the range where it holds. A name that mentions a specific case ("template options") when the thing is general ("block registry") makes readers hunt for templates that do not exist.
Naming interacts with the Taxonomy problem: a vocabulary is a shared model, and every additional near-synonym costs everyone a decision. Preferring an existing term over a new one, and reusing the sibling component's exact prop name rather than inventing a parallel, is what lets independent work converge instead of colliding — see Design System.
Test names are a special case: they should describe the scenario and the expected behavior, not the function under test, so a failure reads as a statement about the system.
See also8
Code Comment
Prose inside source code, useful only when it records a constraint the code cannot state.
Method11 connections
Design System
A shared vocabulary of tokens, primitives, and rules that makes independent work converge.
Design & Interface17 connections
Taxonomy
A controlled vocabulary for classifying things, and the choice between hierarchy, facets, and free tagging.
Meaning & Society33 connections
Code Review
A second person reading a change before it lands, and the practices that make it worth the time.
Version Control & Delivery25 connections
Documentation Rot
Documentation that has drifted from the system it describes, and is now worse than none.
Method27 connections
Chesterton's Fence
Do not remove something whose purpose you cannot explain.
Method18 connections
Information Architecture
How information is organized, labeled, and navigated so people can find what they need.
Data & Content13 connections
Linguistic Relativity
The hypothesis that language shapes thought, and the evidence that has narrowed it considerably.
Meaning & Society17 connections
Related2
Nearby in the graph rather than deliberately chosen. Looser, sometimes surprising.
Linked from53
- BackronymMeaning & Society
An expansion invented after the fact to fit letters that already existed as a word or acronym.
- Broken Windows TheoryMeaning & Society
The hypothesis that visible disorder invites serious crime, and the long dispute over whether the evidence supports it.
- Bus FactorVersion Control & Delivery
The number of people who would have to leave before a project stalls.
- Cache InvalidationWeb Platform
Deciding when a cached value has stopped being correct — famously one of the hard problems.
- Cargo CultMethod
Imitating the visible form of a practice while the mechanism that made it work is absent.
- Chekhov's GunMeaning & Society
The convention that a conspicuously introduced story element must pay off later.
- Chesterton's FenceMethod
Do not remove something whose purpose you cannot explain.
- Code CommentMethod
Prose inside source code, useful only when it records a constraint the code cannot state.
- Collective ActionMeaning & Society
Coordinated action toward a shared goal, and the free-rider problem that makes it hard.
- Confidence TrickMeaning & Society
Fraud that obtains trust first, so the victim hands over the money themselves.
- Conventional CommitsVersion Control & Delivery
A lightweight convention giving commit messages a machine-readable type and scope.
- Cunningham's LawMeaning & Society
The observation that posting a wrong answer online gets a faster correction than asking a question.
- Design SystemDesign & Interface
A shared vocabulary of tokens, primitives, and rules that makes independent work converge.
- EggcornMeaning & Society
A substitution that reanalyzes a phrase into a different but still-plausible meaning.
- FlanderizationMeaning & Society
A recurring character reduced, across a long run, to a single exaggerated trait.
- Folk EtymologyMeaning & Society
Words reshaped to resemble familiar parts, and the false origin stories that reshaping invites.
- FrontmatterData & Content
A metadata block at the top of a text document, separated from the body by delimiters.
- Grammatical GenderMeaning & Society
A noun classification system that forces agreement across a sentence and correlates only loosely with meaning.
- Information ArchitectureData & Content
How information is organized, labeled, and navigated so people can find what they need.
- JaywalkingMeaning & Society
A pedestrian offense whose 1920s American origins are widely read as an effort to shift blame for road deaths onto pedestrians.
- KayfabeMeaning & Society
Professional wrestling's maintained fiction that staged events are real.
- Knowledge GraphMeaning & Society
Information modeled as entities and the typed relationships between them.
- Kuleshov EffectMeaning & Society
Juxtaposed shots produce a meaning that exists in neither shot alone.
- Law of TrivialityMethod
The time spent debating an item is inversely proportional to its actual stakes.
- LegibilityMeaning & Society
Making a system countable and administrable, at the cost of the local knowledge that made it work.
- LetterlockingMeaning & Society
Folding, slitting and sealing a letter so the sheet becomes its own tamper-evident envelope.
- Linguistic RelativityMeaning & Society
The hypothesis that language shapes thought, and the evidence that has narrowed it considerably.
- Ludonarrative DissonancePlay & Games
Friction between what a game's mechanics reward and what its story claims to value.
- MacGuffinMeaning & Society
An object that motivates a plot while remaining substantively irrelevant to it.
- MalaphorMeaning & Society
A blend of two idioms into a third, and the family of errors that reveals how fixed phrases are stored.
- MarkdownData & Content
A plain-text formatting syntax designed to be readable as written, now the default for technical writing.
- Metasyntactic VariableMethod
a placeholder identifier chosen to carry no meaning of its own.
- Modern Monetary TheoryMeaning & Society
A macroeconomic account holding that a currency issuer is constrained by real resources and inflation rather than by revenue.
- MonadComputation & Algorithms
A wrapper type with a way to lift a value in and a way to chain functions that return more wrappers.
- Moral PanicMeaning & Society
A threat to social values amplified by media past any proportion to actual harm.
- Motte and BaileyMethod
Defending a modest claim while trading on a bolder one made under the same name.
- Network EffectMeaning & Society
A good whose value to each user grows as more people use it.
- Overton WindowMeaning & Society
The range of political positions treated as acceptable to hold at a given moment.
- Path DependenceMethod
Outcomes shaped by the sequence of past choices rather than by present merit.
- Plain LanguageMeaning & Society
Writing so that the intended reader can find, understand, and use the information the first time.
- Plausible MechanismMethod
A causal explanation that was inferred rather than tested, and reads as more rigorous for being specific.
- Poe's LawMethod
without a clear signal of intent, sincere extremism and parody of it are indistinguishable.
- Prototype TheoryMeaning & Society
Categories are organized as graded resemblance to a best example rather than defined by necessary and sufficient conditions.
- Rent StrikeMeaning & Society
Tenants collectively withholding rent to force negotiation with a landlord or policymaker.
- Retronasal OlfactionBody & Medicine
Most of what is called taste is smell arriving at the receptors from the back of the mouth.
- Rubber Duck DebuggingMethod
Explaining a problem aloud, in full detail, to a listener who cannot help — and finding the fault while explaining it.
- ShibbolethMeaning & Society
A pronunciation or usage that reveals group membership, historically used as a test with lethal stakes.
- TaxonomyMeaning & Society
A controlled vocabulary for classifying things, and the choice between hierarchy, facets, and free tagging.
- Technical DebtMethod
The future cost of a present shortcut, metaphorically accruing interest.
- Typographic ScaleDesign & Interface
A constrained set of type sizes and their paired line heights and spacing.
- Universal Basic IncomeMeaning & Society
An unconditional cash payment to every member of a population, and its contested design and evidence.
- WikiMeaning & Society
A collection of interlinked pages that anyone with access can edit, named for the Hawaiian word for quick.
- ZettelkastenMeaning & Society
A note-taking method built on small single-idea notes linked to one another.