RFC: Define and enforce a shared set of coding standards

[joshuadarron]

Summary

Over the past few months rocketride-server has grown fast, with a diverse set of contributors landing changes across the C++ engine, Python SDK/tools, and the TypeScript VS Code extension. That growth has been great for velocity — but our code standards have diverged significantly. Formatting, naming, error-handling patterns, and structural conventions now vary widely from file to file and contributor to contributor.

This discussion is a call to agree, as a community, on a shared set of coding standards and then make them enforceable and machine-consumable.

Why now

• Inconsistency tax: reviewers re-litigate the same style debates on every PR.
• Onboarding friction: new contributors (and coding agents) have no single source of truth.
• Diffs polluted by style churn: reformatting noise hides real changes.
• Agent-driven work: we increasingly use coding agents (Claude Code, etc.). They need explicit, structured rules to produce consistent output.

What we want to decide

We're not trying to impose taste from the top down — we want to capture what we collectively value and write it down. Topics to align on:

1. Formatting & linting — per language:
   • Python: ruff config (line length, quote style, import ordering, lint rule set)
   • TypeScript: prettier + eslint config (quotes, semicolons, tabs vs spaces)
   • C++: clang-format style for the engine
2. Naming conventions — files, modules, functions, types, test files.
3. Error handling — e.g. the existing TS conventions (Callout.call() wrapper, always throw AppError, logger.* over console.log). Do we keep, extend, or revise these?
4. Architecture & structure — when to extract modules, separation of concerns, repo layout rules.
5. Testing — coverage expectations, success + error path requirements, test layout.
6. Commits & branches — conventional commits, branch naming.

Proposed deliverables

Once we agree, we implement the standard so it's both human- and agent-readable:

• CLAUDE.md (and sibling agent files — AGENTS.md, GEMINI.md) capturing the standards for coding agents to consume.
• .claude/rules/*.md for focused topic rules (architecture, testing, language conventions).
• Linter/formatter config aligned to the agreed standard, committed to the repo:
  • ruff.toml / pyproject.toml for Python
  • .prettierrc + eslint config for TypeScript
  • .clang-format for C++
• CI enforcement — lint/format checks gating PRs so the standard stays enforced, not aspirational.
• A short CONTRIBUTING.md linking it all together.

How to participate

Please weigh in with:

• Standards you feel strongly about (and why).
• Existing conventions worth keeping vs. dropping.
• Tooling preferences and any hard constraints (e.g. engine build requirements).
• Volunteers to own a language section.

Once discussion settles, we'll open tracking issues per deliverable and land the configs + agent files incrementally to avoid one giant reformatting PR.

[github-actions[bot]]

[joshuadarron]

.claude/rules/code-style.md

Naming

Functions are named as a verb phrase that states the action. Read the name and you know what it does without reading the body.

• Good: transformStringIntoBinary, convertToGenericType, addMultipleIntegers
• Bad: handle, process, doStuff, helper

Variables are named as nouns describing what they hold. Singular for one, plural for a collection.

• Good: convertedString, user (one individual), users (a list)
• Bad: data, temp, val, x

Naming is literal, not clever. If you cannot tell what a variable holds or what a function does at a glance, the name is wrong. No abbreviations, no vague nouns.

Comments

Every function has a doc comment in the language-native format: docstring (Python), JSDoc (TypeScript), Doxygen (C++). The comment carries a description when the name alone does not fully convey intent. If the name says everything, the doc comment can be a single line; it is still required so tooling and agents have a consistent anchor.

Function size and responsibility

A function does one thing. This repo is built for reuse, and functions that bundle multiple actions cannot be reused, only copied.

Target: 10 lines or fewer per function. A function pushing past that is a signal it is doing more than one thing and should be decomposed.

Promise handling (TypeScript)

Prefer resolving each promise through a callout function that returns either a response or an error, so resolution is handled per async call. Avoid wrapping several awaits in one try/catch that swallows them all under a single generic handler. Each async operation owns its own success and failure path.

Readability

Code reads top to bottom, left to right, like prose. A reader should follow the flow without jumping around to understand what a line is doing. Clarity at a glance is the bar. If a reader has to stop and decode, the code is wrong even if it runs.