clean up
This commit is contained in:
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: LSN-0025
|
||||
ticket: tile-bank-vs-glyph-bank-domain-naming
|
||||
title: Rename Artifact by Meaning, Not by Token
|
||||
created: 2026-04-10
|
||||
tags: [gfx, runtime, naming, refactor, documentation]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The runtime used `TileBank` as the name of the concrete graphical bank artifact while also using `tile` for map, layer, and geometric concepts such as `TileLayer`, `TileMap`, and `TileSize`. This overloaded the term `tile` across two different meanings.
|
||||
|
||||
The implemented migration renamed only the concrete bank artifact to `GlyphBank` and renamed the corresponding asset-bank contract from `BankType::TILES` to `BankType::GLYPH`, while explicitly preserving `TileLayer`, `TileMap`, and `TileSize`.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Glyph Bank Domain Naming Contract
|
||||
|
||||
**What:**
|
||||
Rename the concrete graphical bank artifact and its runtime interfaces to `GlyphBank`, but keep tile-domain structures unchanged where `tile` still correctly describes layers, maps, grids, and geometry.
|
||||
|
||||
**Why:**
|
||||
The goal was domain clarity, not behavior change. The project needed a more precise name for the concrete graphical bank without reopening rendering architecture or erasing valid uses of `tile`.
|
||||
|
||||
**Trade-offs:**
|
||||
This requires more care than a blind search-and-replace. The migration is broader editorially, but safer semantically, because it avoids damaging concepts that still belong in the tile domain.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Rename by artifact meaning, not by string token frequency.
|
||||
- When a term is overloaded, split the rename along domain boundaries instead of trying to enforce total lexical uniformity.
|
||||
- Let the runtime contract adopt the new canonical artifact name (`GlyphBank`, `BankType::GLYPH`) while preserving existing terms for excluded concepts (`TileLayer`, `TileMap`, `TileSize`).
|
||||
- Apply the same semantic rule to docs and lessons, not only to code.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Blind replacement would have incorrectly renamed tile-layer and tile-size concepts that were intentionally out of scope.
|
||||
- Partial renames create mixed vocabulary, which is worse than either old or new terminology used consistently.
|
||||
- Historical documentation is especially easy to corrupt if rewritten mechanically instead of by artifact meaning.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- A naming refactor can be rename-only in behavior while still requiring architectural discipline in wording.
|
||||
- Use one canonical name per artifact, but do not force unrelated domains to share that rename.
|
||||
- Documentation migrations should follow the same semantic boundary as code migrations, or the codebase will drift back into conceptual ambiguity.
|
||||
Reference in New Issue
Block a user