Naming

Naming

Vanilla conventions (snake_case in Rust, kebab-case in JS/TS, PascalCase exports, use-* hooks) are table stakes — assume them. This document is about the observations on top: what a name commits you to, what it reveals, and what it costs when it's wrong.

Name first

Pick the name before the types, before the tests, before the file exists. If the name doesn't come easily, the design isn't ready — don't start coding; sharpen the concept until the name falls out. Maintainability is downstream of naming. How a module grows, how cleanly it retires, how safely it can be deleted — all of it is decided at the moment you choose what to call it.

A strict, honest name is a scope gate

A name's primary job here is to refuse the wrong content. A module called painter should feel actively wrong to host a layout helper; a package called @grida/cmath should feel wrong to host color logic. The strictness is deliberate — it is the mechanism that keeps features from leaking into each other.

"Strict" requires "honest." A name that no longer describes what's inside has stopped being a gate: it won't reject foreign additions, and new readers can't trust it. When contents drift past the name, you have two moves — rename to match what the module has become, or extract the drifted pieces out — and you must pick one promptly. Letting a name go stale is how codebases rot quietly.

Three consequences cascade from the gate discipline, and together they produce the current repo structure:

1. Modules stay shallow. You will rarely see a module nested deeper than two levels inside a crate's src/ or a package's src/. When you're tempted to grow a third level, the parent's name has stopped describing what's inside — flatten or extract, don't nest.
2. Flatten with prefixed siblings, or collapse into one file. Before reaching for a subdirectory, ask whether the new thing is a sibling variant of an existing file (painter.rs + painter_debug_node.rs + painter_geometry.rs) or whether it collapses into the existing file. Both preserve the parent's scope; a new subdirectory quietly widens it.
3. If it resists flattening, it is a new module. The thing that won't fit under the strict name doesn't belong there. It wants its own tiny, agnostic package or crate. The repo has many small @grida/* packages and small crates precisely because this extraction was made each time a sibling would have diluted the parent's name.

One module, one thing

The gate only works because each module commits to one thing. Two-thing modules can't enforce either scope — the name becomes ambiguous as a filter, and new additions slip in under whichever reading is convenient. When you notice a module doing two things, pick the primary, rename for it, and extract or delete the other. The repo's proliferation of tiny packages is this choice compounded.

The diff test

A well-named module exhibits two properties under change. Treat them as the measurable signal that naming is doing its work:

1. A feature change lands in one file, or a tight set of sibling files. Diffs that scatter across unrelated modules mean the boundary isn't where the name implies it is.
2. The file can be deleted with confidence. Remove it and the compiler or test suite will tell you exactly what else must go — or nothing does. If removal requires a cross-cutting hunt through unrelated names, the module was leaking all along.

A codebase where neither test passes easily has a naming problem dressed up as an architecture problem. The inverse is the real payoff: when both tests pass, code grows by adding siblings or spawning small packages, and it retires by a single git rm.

A name is a contract at the scope of its reach

The cost of a bad name is rename friction × fanout. Fanout is set by where the name is visible, and the difference is severe:

• A directory is seen by whoever walks the tree. Rename cost: git mv + import updates. Cheap.
• A published identifier (@grida/cg, Cargo name) is seen by every call site in every branch in every downstream repo. Rename cost: coordinated migration, deprecation window, semver break.

This asymmetry is why the directory name and the published name can diverge. packages/grida-canvas-cg publishes as @grida/cg: the long directory pays for browsability (the canvas family clusters in the file tree) where rename is cheap; the short scope pays for ergonomics where rename is expensive. The Rust side, by contrast, aligns — the engine repo's crates/grida (gridaco/nothing) publishes as grida because the core crate is also the project's public namespace, and keeping the two in lockstep removes a name to remember. Two different trade-offs; pick per surface. Invest heavily in a name before it escapes its file; once it's a public surface, the name is a commitment.

A name is a diagnostic

A name that feels hard to pick is telling you something about the module, not your vocabulary. Common tells:

• Tempted to stamp the child with the parent's name. The parent isn't carrying its scope. Fix the parent — don't double-stamp. grida-canvas/canvas-text/ is the symptom; grida-canvas/text/ is the correction.
• Can't name the new thing without qualifying against a sibling. The sibling is too close — you haven't factored the shared abstraction, or the two don't belong in this parent.
• The strict name won't stretch to fit what you want to add. This is the system working. The answer is never to loosen the name; it's to flatten the addition as a sibling, or extract it.
• Need a README paragraph to explain the module's name. The boundary is wrong. Names that require prose describe accidental groupings.

Naming is the cheapest design review you get. Listen to it when it resists.