Naming

Naming

Scope: names in Rust code. Typst sources — the embedded @tola/* packages, generated scaffolding, and site recipes — follow Typst's conventions and the site vocabulary the tola skill records.

A name carries 3 facts: what represented, who owns it, when valid. Cannot answer all 3 from name + owner → wrong name.

Start from the domain

Name the entity or invariant, not the storage technique: SourceSnapshot holds frozen source identity; BytesBlob says only how bytes are kept.

• Type: the entity or invariant it represents.
• General term: earned by breadth carried, never by default — the precise word when several distinct things really share it (one Diagnostic for the record every producer emits; one Source for every file the compiler reads). Narrowed to one concrete thing, an earned word still describes it; an unearned one collapses — was filler all along.
• Function: the operation, and the value produced when not obvious.
• Module/file: one cohesive responsibility — not a phase of work, not a bucket for unrelated code.
• Collection: what members are: DeclaredOutputs, not outputList.
• Boolean: reads as the predicate held: is_draft, not draft_flag.
• Transformation: names input and output: normalize_path, not process_path.
• Error: the contract that failed: MissingPackageRoot, not InvalidInput.
• Cache: the reusable value + boundary where it stops being valid.

Avoid

• Never catalog in Tola-owned identifiers, modules, files, directories — incl case variants and compounds (PackageCatalog, package_catalog). Name the actual entity: PublishedPackages, PackageVersions, IconCollections. Another vague container word does not fix it. Preserve user-authored names and upstream-API spellings; do not adopt them for Tola's own.
• Placeholder/abstraction nouns: data, info, item, object, context, state, result, policy, entry, record, element, input, fixture, probe. Name what the value holds or decides: ReferenceLevel not ReferencePolicy; SlugSeparator not SeparatorPolicy; ImportPath not Input; a test helper named for the value it returns (html_page, asset_route), never the technique that builds it.
• Gerund for a value the domain already names: reading for a pronunciation or compiler read; processing/handling for the thing they produce. Established term wins — pronunciation, read, read evidence.
• Role suffixes hiding a design nobody can name: Manager, Processor, Handler, Helper, Util.
• Participant the value does not depend on: authored, provided, handled, processed, managed. Name states the relationship carried (configured, resolved, declared), not who/what produced it. Participant earns its place only when it changes meaning — imported_by for a diagnostic raised inside a package.
• Test either word: state the relationship as a rule another file could follow. resolved passes — the filesystem's own spelling, symlinks followed. authored fails — no rule distinguishes it from path.
• Near-synonym for a word the repo already uses. Established term wins.
• Abstraction whose boundary and invariant cannot be said in its name.
• Type named by listing what it holds: ResolvedSiteConfigWithSiteDirectory names a field pair, not the invariant making the pair necessary (OwnedSiteConfig). Conjunction only when both parts are domain data that must travel together and no single noun covers them; when one part is plumbing merely keeping the other valid, name the invariant instead. Longer is the symptom, not the fix.
• Stutter with the owner that gives context: routes::routes, Route::route_path, Connection::connect_connection. Inside routes, a function states the operation (site_routes, respond), a type the entity (Route); the module already said where they live.