Naming Conventions

This page records current naming conventions and intended direction. It is a development standard, not a claim that every historical file already conforms.

Source file prefixes

Unofficial search families

Not every useful code group is a formal prefix. Some families are practical search handles: they help developers find related commands, helpers, tests, generated reports, and proof scripts. They are useful for navigation, but they are not stable API promises unless promoted by a source contract.

Search families should be documented as discovery aids. If a family becomes a product-facing contract, promote it into the command catalog, DOTREF/help metadata, and this page's formal prefix or command-family sections.

Necessary directory trees

The development tree is intentionally wider than the public product tree. The useful mental model is not "everything ships"; it is "source, proof, generated documentation, and staged publication each have a role."

Development tree

D:\code\ccode
|-- src\                 runtime source: CLI, xbase, indexes, memo, GUI bridges
|-- include\             public/internal headers and engine contracts
|-- dottalkpp\           runtime data, scripts, generated reports, maintenance lanes
|-- selfdoc\             documentation collection and source-contract probes
|-- labtalk\             Laboratory Campus plans, reports, products, and lessons
|-- tools\               manualgen, datadict, help, and support tooling
|-- scripts\             smoke scripts, build helpers, and DTS examples
|-- tests\               regression and manual test surfaces
|-- docs\                source-side specifications and design records
|-- apps\                app/workbench experiments
|-- pycrud\              Python CRUD/GUI lane
|-- py\                  Python helpers and experiments
|-- contracts\           contract and coding-standard support material
|-- cases\               case-study and proof material
|-- samples\             sample data/code surfaces
|-- results\             generated or captured run results
|-- build*\              local build outputs, not product truth
`-- third_party\         external dependencies and vendored support

Public website source and staged product tree

D:\dev\x64base-site
|-- app\                 Next.js route pages and public section shells
|-- content\             MDX documentation and product copy
|-- config\              navigation/sidebar/site configuration
|-- components\          shared website components
|-- public\              images, diagrams, screenshots, and static assets
`-- scripts\             build, export, and staging helpers

C:\x64base
|-- dottalk-webui\public-site\   staged static website mirror
|-- dottalkpp\                   staged runtime/source mirror when synced
|-- pycrud\                      staged Python CRUD/GUI lane when synced
`-- README / manifests           publication and staging notes

The C:\x64base tree is the publication staging area. Generated data such as Bible SQL and LMDB artifacts should be regenerated as needed rather than treated as permanent source truth.

Command implementation convention

Command files should use cmd_<canonical_command>.cpp where practical. The command's public identity should be aligned across:

1. command registration in the shell.
2. the source contract near the implementation.
3. DOTREF entry in include/dotref.hpp.
4. HELP/CMDHELP/CMDHELPCHK rows.
5. website command catalog and manualgen output.

Compatibility or historical references can live in foxref.hpp; current DotTalk++ commands belong in DOTREF unless intentionally hidden or internal.

Command-shell lambda registration

Some commands are registered directly in the command shell with lambda handlers rather than as standalone cmd_*.cpp functions. That is allowed, but it needs a convention because lambda registration is easy to lose in documentation scans.

Lambda-registered commands should:

• use an explicit canonical command name and alias list in the registration call.
• include a nearby @dottalk.usage v1 contract or reference a reviewed contract block.
• state whether the lambda is report-only, session-mutating, table-mutating, filesystem-mutating, external-app-active, or network-active.
• remain small; if the lambda grows beyond simple dispatch/glue, move behavior into a named helper or cmd_*.cpp implementation.
• be visible to command catalog generation, DOTREF review, and CMDHELPCHK.
• avoid hiding mutators, filesystem writers, or external app launchers inside inline lambdas.

Preferred shape:

registry.registerCommand("COMMAND", aliases, [](ShellContext& ctx, Args args) {
  return run_named_command_helper(ctx, args);
});

Avoid putting complex business logic directly inside the lambda. The lambda should usually bind command syntax to a named implementation, not become the implementation.

Education command convention

Education commands use edu_ when they are primarily teaching surfaces. If an education command is also a normal command-shell command, document both identities:

• source file prefix: edu_
• shell command: public command name such as ASCII, RETRO, BBOX, or IDX
• lesson lane: Laboratory Campus / education feature page
• proof: transcript, screenshot, source contract, or .dts lab

Student extension examples should live under extension paths and use explicit sample status. They should not overwrite core command names.

Function convention

Function implementations and registrations should use fn_ or a clearly grouped function catalog source. Functions should state:

• canonical function name.
• aliases, if any.
• argument count and type expectations.
• return type.
• whether evaluation is pure or can read/mutate external state.
• whether the function is core, sample-extension, or planned.

Scalar functions used by mutating commands such as CALC, CALCWRITE, and REPLACE deserve extra review because expression behavior can become data mutation.

Script and proof naming

.dts files should be named for intent and risk:

Every promoted .dts lesson should state:

• required dataset.
• expected read/write behavior.
• whether it is safe observation or mutation.
• expected output or transcript anchor.
• proof status.

Documentation convention

Website and manual pages should avoid presenting active lanes as finished products. Use these status labels consistently:

• runtime-evidenced
• source-evidenced
• help-catalog-evidenced
• generated-reviewed
• planned-or-in-progress
• review-needed

If a page describes a planned lane, it should name the lane and avoid implying the command syntax is implemented.