Coding Standards

Code Style

The current codebase can be used as a guide for formatting conventions. Additional guidelines are provided below.

Universal formatting rules

The following applies to all source files (Rust, Python, Cython, shell, etc.):

Use spaces only, never hard tab characters.
Lines should generally stay below 100 characters; wrap thoughtfully when necessary.
Prefer American English spelling (color, serialize, behavior).

Shell script portability

Shell scripts in this repository use bash (not POSIX sh) and must be portable across Linux and macOS. User-facing scripts (e.g., scripts/cli/install.sh) must also work on Windows via Git Bash or WSL.

Shebang: Always use #!/usr/bin/env bash for portability.

Common pitfalls: GNU and BSD utilities differ between Linux and macOS:

Command	Linux (GNU)	macOS (BSD)	Portable solution
`sed -i`	`sed -i 's/…'`	`sed -i '' 's/…'`	Use backup extension: `sed -i.bak 's/…'`
`stat` (file size)	`stat -c%s file`	`stat -f%z file`	Detect with `stat --version`
`sha256sum`	`sha256sum file`	N/A	Use `shasum -a 256` or detect
`readlink -f`	Works	N/A	Avoid, or use `realpath`
`grep -P` (PCRE)	Works	N/A	Use `-E` (extended regex) instead
`date` (nanoseconds)	`date +%N`	N/A	Use `$RANDOM` for cache‑busting

Bash version: macOS ships with bash 3.2; avoid bash 4+ features in user-facing scripts:

Feature	Bash version	Alternative
Associative arrays (`declare -A`)	4.0+	Use files or simple arrays
`readarray` / `mapfile`	4.0+	Use `while read` loops
`${var,,}` / `${var^^}` (case)	4.0+	Use `tr '[:upper:]' '[:lower:]'`

CI scripts (scripts/ci/*) run on Linux runners, so bash 4+ and GNU tools are acceptable there.

Comment conventions

Generally leave one blank line above every comment block or docstring so it is visually separated from code.
Use sentence case – capitalize the first letter, keep the rest lowercase unless proper nouns or acronyms.
Do not use double spaces after periods.
Single-line comments must not end with a period unless the line ends with a URL or inline Markdown link – in those cases leave the punctuation exactly as the link requires.
Multi-line comments should separate sentences with commas (not period-per-line). The final line should end with a period.
Keep comments concise; favor clarity and only explain the non-obvious – less is more.
Avoid emoji symbols in text.

Doc comment mood

Rust doc comments should be written in the indicative mood – e.g. "Returns a cached client."

This convention aligns with the prevailing style of the Rust ecosystem and makes generated documentation feel natural to end-users.

Terminology and phrasing

Error messages: Avoid using ", got" in error messages. Use more descriptive alternatives like ", was", ", received", or ", found" depending on context.
- ❌ "Expected string, got {type(value)}"
- ✅ "Expected string, was {type(value)}"
Spelling: Use "hardcoded" (single word) rather than "hard-coded" or "hard coded" – this is the more modern and accepted spelling.
Error variable naming: Use single-letter e for caught errors/exceptions:
- Rust: Err(e) not Err(err) or Err(error), and |e| not |err| in closures
- Python: except SomeError as e: not as err: or as error:

Naming conventions

Internal fields: Abbreviations are acceptable for private/internal fields (e.g., _price_prec, _size_prec) to keep hot-path code concise.
User-facing API: Use full, descriptive names for public properties, function parameters, return types, and metric names/labels (e.g., price_precision, size_precision). This prevents abbreviated terminology from leaking into dashboards or alerts.
Error messages and logs: Use full words for clarity (e.g., "price precision" not "price prec"). The user should never see abbreviated terminology.

Formatting

For longer lines of code, and when passing more than a couple of arguments, you should take a new line which aligns at the next logical indent (rather than attempting a hanging 'vanity' alignment off an opening parenthesis). This practice conserves space to the right, keeps important code more central in view, and survives function/method name changes.
The closing parenthesis should be located on a new line, aligned at the logical indent.
Multiple hanging parameters or arguments should end with a trailing comma:

python

long_method_with_many_params(
    some_arg1,
    some_arg2,
    some_arg3,  # <-- trailing comma
)

Commit messages

Here are some guidelines for the style of your commit messages:

Limit subject titles to 60 characters or fewer. Capitalize subject line and do not end with period.
Use 'imperative voice', i.e. the message should describe what the commit will do if applied.
Optional: Use the body to explain change. Separate from subject with a blank line. Keep under 100 character width. You can use bullet points with or without terminating periods.
Optional: Provide # references to relevant issues or tickets.
Optional: Provide any hyperlinks which are informative.

Gitlint (optional)

Gitlint is available to help enforce commit message standards automatically. It checks that commit messages follow the guidelines above (character limits, formatting, etc.). This is opt-in and not enforced in CI.

Benefits: Encourages concise yet expressive commit messages, helps develop clear explanations of changes.

Installation: First install gitlint to run it locally:

bash

uv pip install gitlint

To enable gitlint as an automatic commit-msg hook:

bash

prek install --hook-type commit-msg

Manual usage: Check your last commit message:

bash

gitlint

Configuration is in .gitlint at the repository root:

60-character title limit: Ensures clear rendering on GitHub and encourages brevity while remaining descriptive.
79-character body width: Aligns with Python's PEP 8 conventions and the traditional limit for git tooling.

:::note Gitlint may be enforced in CI in the future, so adopting these practices early eases the transition. :::