Coding Standards

These standards are part of the SelfDoc system. Code should be readable by a maintainer, harvestable by tools, and honest about its mutation and proof boundaries.

Code

• Prefer small functions with explicit ownership.
• Use stable command, field, table, and lane names.
• Keep runtime behavior and public documentation in sync.
• Route filesystem, network, external-process, and database mutation through explicit command contracts.
• Preserve existing worktree changes; do not use broad rewrites for narrow documentation or command updates.

Command Header Contracts

Contracts are not decorative comments. They are the public source-of-truth layer that lets DotTalk++ connect implementation, HELP, CMDHELP, SelfDoc, manualgen, diagrams, website pages, and runtime proof. If a command can be run by a user, called from DotScript, surfaced in HELP, included in CMDHELPCHK, or promoted to the website, it needs a contract.

The contract should be close to the implementation, easy to harvest, and honest about status. A reader should be able to tell whether the command is read-only, session-mutating, table-mutating, filesystem-mutating, network-active, externally active, or publication-active without reading the whole command body.

Every command intended for HELP, CMDHELP, SelfDoc, manualgen, or the website should have a leading @dottalk.usage v1 block or an equivalent reviewed contract. Preferred fields:

@dottalk.usage v1
owner: DOT|COMMAND
command: COMMAND
aliases: ALIAS1, ALIAS2
category: ...
status: supported|experimental|sample-extension|...
noargs: usage|report|status|...
effect: report|display|evaluate|mutate|rebuild|session-control|mixed|network-or-file|...
mutates: none|session|shell-exit-state|table-data|table-buffer|memo|index|filesystem|helpdata|metadata|manualgen|sidecar|...
usage-access: COMMAND USAGE
summary:
  Short behavior statement.
usage:
  COMMAND USAGE
  COMMAND ...
notes:
  Runtime boundary notes and compatibility behavior.
risk:
  reads_files: yes|no
  writes_files: yes|no
  launches_external_app: yes|no
  network_access: yes|no
  mutates_table_data: yes|no
  writes_table_buffer: yes|no
  writes_memo: yes|no
  mutates_index: yes|no
  requires_open_table: yes|no
  requires_current_record: yes|no
related:
  HELP
  CMDHELPCHK
@dottalk.end

These headers are harvested into comments evidence, HELP/CMDHELP rows, validation reports, manualgen, diagrams, and website pages.

Required Contract Questions

Before a command is considered documented, its contract should answer:

• What is the canonical command name?
• Are there aliases or compatibility spellings?
• Is it current, planned, experimental, canary, sample-extension, or deprecated?
• What happens with no arguments?
• Does it read or write table records?
• Does it write a table buffer instead of the physical DBF?
• Does it mark fields dirty or stale?
• Does it write memo payloads or memo object references?
• Does it mutate indexes, index metadata, order state, or LMDB/CDX/CNX files?
• Does it read or write ordinary files?
• Does it launch an editor, browser, image viewer, shell, URL handler, SFTP/SSH tool, or other external app?
• Does it touch HELP DATA, CMDHELPCHK, SelfDoc, manualgen, metadata, message catalogs, or publication artifacts?
• What proof or smoke path should validate it?

Mutation Classes

Use narrow mutation labels. Avoid saying only mutates: yes.

Special Command Families

Some families require extra care because they can look harmless while crossing a real boundary.

• Data mutators: REPLACE, REPLACE_MULTI, MULTIREP, CALCWRITE, assignment-capable CALC, APPEND, APPEND BLANK, DELETE, RECALL, PACK, and ZAP must state physical-write versus buffered-write behavior.
• Index mutators: INDEX, REINDEX, CDX, CNX, LMDB, BUILDLMDB, SET CDX, SET CNX, SET LMDB, SET ORDER, and related compact forms must state whether table data, index files, order state, or backend environments are changed.
• Filesystem and external tools: COPY, EXPORT, IMPORT, DDL FETCH, WEB, URL, IMAGE, EDIT, shell commands, SFTP/SSH, archive, and zip commands must state path resolution, writes, external launch behavior, and network behavior.
• SelfDoc/help/manual commands: HELP, CMDHELP, CMDHELPCHK, MAINT, DDICT, MANUAL, MANSTAR, BBOX, message-manager commands, and contract scanners must say whether they are report-only or authorized to mutate catalogs.
• Session lifecycle: QUIT, EXIT, CLOSE, WORKSPACE, SELECT, USE, SET, and path/language settings must state whether they mutate only session state or also close files, release areas, or change persistent data.

DOTREF And Registry Alignment

For user-facing commands, three surfaces should stay aligned:

1. Runtime registration in the command registry.
2. Source contract in the implementation file.
3. Native DotTalk++ reference entry in include/dotref.hpp.

Compatibility-only or historical material can live in foxref.hpp, but current DotTalk++ commands belong in DOTREF. If a command is intentionally omitted from DOTREF, the omission should be documented as internal, deprecated, or hidden.

Command-shell lambda registration is allowed, but lambda handlers still need command contracts, DOTREF review, and catalog visibility. Inline lambdas should stay small and delegate meaningful behavior to named helpers or cmd_*.cpp implementations when the command grows. See Naming Conventions.

Comments and Collection

• Put command-level contracts at the top of the implementation file.
• Keep usage examples ASCII-safe unless the file already requires Unicode.
• Mark compatibility aliases explicitly.
• State whether a command is read-only, report-only, filesystem-mutating, DBF-mutating, HELP-mutating, or externally active.
• Use status labels such as planned, canary, experimental, or review-needed instead of burying uncertainty.
• If a command writes HELP DATA, DBF files, sidecars, fetched files, or launches an external app, say so in mutates: and risk:.

Current tooling includes tools/comments/upsert_source_comment_contract.py for staged source-comment imports and tools/contracts/contract_scan.py for contract-lane inventory.

Safeguards

• Validation commands should be report-only unless a specific work order authorizes writes.
• CMDHELPCHK, MAINT, DDICT, and MANUAL should remain read-only inspection surfaces unless their source contract changes.
• CMDHELP BUILD is allowed to mutate HELP DATA because that is its explicit command contract.
• DDL FETCH, WEB FETCH, IMAGE, EDIT, shell, and SFTP-style commands must document external app, network, and filesystem boundaries separately from table mutation.
• Manualgen publication replacement requires review; dry-run artifacts are not automatic publications.

Accessibility and Inclusive Design Standards

x64base is a scholastic system, so accessibility and inclusive design are ground-level engineering requirements. Public pages, generated manuals, diagrams, downloads, and UI surfaces should target WCAG 2.2 AA-style behavior unless a platform constraint is explicitly documented.

Use these requirements for website work, generated documentation, GUI/TUI work, manuals, and published artifacts:

• Non-text content needs a text alternative. Image links need real link text, alt text, or an aria-label; complex diagrams need captions and a nearby text summary.
• Color must never be the only signal. Status should include text labels such as runtime-evidenced, planned, canary, review-needed, or public-ready.
• Normal prose must remain readable with browser zoom and operating-system scaling. Avoid fixed pixel-only layouts that force horizontal scrolling for ordinary reading.
• Keyboard navigation is required for links, menus, tabs, cards, downloads, forms, and command surfaces. Visible focus state is required.
• Pages should use semantic landmarks and heading order: one logical h1, meaningful h2/h3 hierarchy, header, nav, main, and footer where appropriate.
• Icon-only controls need accessible names. Decorative icons should be hidden from assistive technology.
• Tables need real headers. Command catalogs, function catalogs, feature matrices, and comparison tables should remain understandable to screen readers.
• Code blocks should not be the only explanation. Provide a short prose summary for command examples, DotScript examples, and generated snippets.
• Motion should respect prefers-reduced-motion; avoid flashing or decorative animation that can interfere with reading.
• Downloadable PDFs, DOCX files, large reports, and decks should have an HTML or Markdown summary when possible, plus type, date, source/provenance, proof status, and accessibility status.

Accessibility status is part of provenance. Promoted artifacts should carry labels such as:

accessibility:
  alt_text: ready|needed|not-applicable
  text_summary: ready|needed|not-applicable
  keyboard_path: checked|needed|not-applicable
  contrast_review: checked|needed
  screen_reader_review: checked|needed

Generated reports may start as needed, but reviewed website/manual promotion should not hide that status.

Docs

• Short paragraphs.
• Include command examples.
• Define terms once and reuse consistently.
• Preserve proof labels.
• Preserve accessibility labels for promoted diagrams, screenshots, manuals, downloads, and generated reports.
• Link website pages back to command catalogs, feature crosswalks, SelfDoc reports, and manualgen artifacts.
• Treat the website as a reviewed derivative of source, contracts, HELP, metadata, comments evidence, CMDHELPCHK, and manualgen.