Coding and component guidelines¶
Start at Platform for public setup and the
package map for responsibilities. Folders describe functions;
host.py generally controls a child and worker.py/process.py holds its entrypoint.
A runner/controller is an object, not an implicit thread.
Ownership and dependencies¶
- Platform constructs shared resources and registers roots; lower layers do not create it.
- Controllers own their runner/market; runners own method-specific background resources.
- Domain rules do not import ORM/UI. Persistence handles file/SQL IO, not trading decisions.
- Financial changes follow the shared transaction path; publish RAM only after commit.
- Agent local tools remain in Agent; platform commands retain validation and financial ownership.
- Qt widgets display data and submit commands through existing controllers, not a second engine.
- Public package initializers stay lightweight and avoid eager optional Qt imports.
The boundary tests check selected import directions. They do not detect all private-field coupling or guarantee lifecycle correctness.
Functions and interfaces¶
Give a function one clear operation with a name explaining its purpose. Separate validation, resource assembly, business work and rendering when they have independent responsibilities. Keep genuinely shared helpers close to their owner; do not create a generic utilities dump or a class whose only purpose is forwarding another class's methods. Name the owning use-case service explicitly inside transaction boundaries; avoid searching multiple services for a string method name. UI builders return named controls or emit signals instead of attaching undocumented attributes to a caller.
Document boundary inputs/results, units, synchronous waiting, side effects, state ownership and failure behavior. Prefer named types/Protocols for stable internal shapes. Keep wire values detached and finite JSON. Do not introduce contract-version labels or business hashes as a substitute for a clear interface. Normal distribution versions, external protocol fields and database migration identifiers still have their legitimate meanings.
Within a Python class/module, define helper dependencies before their callers, consistent with the existing project rule. Avoid modifying another class's private fields when extending an adapter. Existing such coupling is debt to remove, not a pattern to copy.
Public API documentation¶
Every public Platform method needs parameter/return annotations and a docstring explaining
when to use it, what it does, what is returned, and the next step. Include useful examples,
units/defaults, blocking work, lifecycle/resource ownership and major failure conditions.
Fixed dictionary shapes belong in application/api_types.py; these are descriptions,
not new runtime wrappers. Distinguish saving, preparing, Play, Pause, terminal state and close.
Use simple English that a new maintainer can follow. Keep development-stage names out of
function explanations, comments and user errors.
Formatting and tests¶
Python uses four-space indentation, a 100-column target, Black and Ruff pinned in
requirements-dev.txt, with settings in pyproject.toml. make python-quality checks
sim_platform, tests/platform and tools. Ruff checks basic errors, likely bugs,
inconsistent returns and functions with more than 20 branches; split such a function into
named steps instead of silencing the rule. Mypy checks the packages listed under
[tool.mypy] in pyproject.toml, where every function must be annotated. Type checking is
adopted one package at a time: annotate a package, add it to that list, and it stays checked.
C++ uses C++17, the root .clang-format and Doxygen-style interface comments in headers.
Run make format-check with a compatible clang-format when changing native code.
Desktop frontend pages are built from small section functions that each return one part
of the page (for example toolbar, stats, records). Add a section function instead of
extending one long template string, and keep the class names that updateWorkspace swaps.
Buttons, forms and published events each have one table or binder to extend; see the
frontend ownership map.
Choose independent expected behavior, not assertions that repeat the implementation. Keep test fixtures reusable without manually invoking another TestCase's setup. Use controlled clocks for ordering/deadline tests; real elapsed-time/performance experiments are separate. See verification for commands, CI scope and known gaps.
Section index · All documentation