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.
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 behaviour, not the function under test, so a failure reads as a statement about the system.
See also8
Hand-picked in the note itself — the neighbours worth reading next.
Code Comment
Prose inside source code, useful only when it records a constraint the code cannot state.
Method9 connections
Design System
A shared vocabulary of tokens, primitives, and rules that makes independent work converge.
Design & Interface9 connections
Taxonomy
A controlled vocabulary for classifying things, and the choice between hierarchy, facets, and free tagging.
Meaning & Society12 connections
Code Review
A second person reading a change before it lands, and the practices that make it worth the time.
Version Control & Delivery15 connections
Documentation Rot
Documentation that has drifted from the system it describes, and is now worse than none.
Method20 connections
Chesterton's Fence
Do not remove something whose purpose you cannot explain.
Method11 connections
Information Architecture
How information is organised, labelled, and navigated so people can find what they need.
Data & Content11 connections
Linguistic Relativity
The hypothesis that language shapes thought, and the evidence that has narrowed it considerably.
Meaning & Society11 connections
Related2
Nearby in the graph rather than deliberately chosen. Looser, sometimes surprising.
Linked from19
Notes elsewhere in the wiki that reach for this one.
- Cache InvalidationWeb Platform
Deciding when a cached value has stopped being correct — famously one of the hard problems.
- 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.
- Conventional CommitsVersion Control & Delivery
A lightweight convention giving commit messages a machine-readable type and scope.
- Design SystemDesign & Interface
A shared vocabulary of tokens, primitives, and rules that makes independent work converge.
- FrontmatterData & Content
A metadata block at the top of a text document, separated from the body by delimiters.
- Information ArchitectureData & Content
How information is organised, labelled, and navigated so people can find what they need.
- Knowledge GraphMeaning & Society
Information modelled as entities and the typed relationships between them.
- Linguistic RelativityMeaning & Society
The hypothesis that language shapes thought, and the evidence that has narrowed it considerably.
- MarkdownData & Content
A plain-text formatting syntax designed to be readable as written, now the default for technical writing.
- 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.
- Rent StrikeMeaning & Society
Tenants collectively withholding rent to force negotiation with a landlord or policymaker.
- 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.
- 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.