docs/coding-policy.md
This file is the Pyxel coding policy. It applies to every in-scope file (see Verification > Scope) and is enforced through the steps in Verification.
Code on the hot paths is shaped around minimum cost. The hot paths are:
On hot paths, idiomatic patterns that hide cost are not used.
Vec::new, format!, Box::new in inner loops); avoidable copies or type conversions; bounds checks in tight loops; missed SIMD, loop-unrolling, or inlining opportunities.Outside hot paths, code stays idiomatic and readable. Micro-optimization is reserved for the listed hot paths.
for x in xs { f(x) } in a config loader is preferred over a hand-unrolled alternative.Mechanical naming rules apply first; subjective taste is a last resort.
A symbol referenced from more than one file uses the same base name at every site (function and type names, CSS classes, HTML IDs, i18n keys, public API entries). Suffixed variants of the base name are allowed when each variant is exposed as a separate public entry.
pyxel-core function generate_bgm keeps the same base name in pyxel-binding/src/*_wrapper.rs and python/pyxel/__init__.pyi; if it is split for separate exposure, the split uses suffixes (generate_bgm_mml, generate_bgm_json) rather than a renaming.Names that signal confusion or rewrite leftovers are rewritten.
titleBlock in one file, titleDiv in another for the same UI element) — anti-pattern; an asymmetric verb pair (saveForGist alongside loadFromGist and loadFromUrl) — anti-pattern; stutter or type prefix (Canvas.drawCanvas(), strFoo) — anti-pattern.A language's idiomatic abbreviations are kept as-is.
i for a loop counter and e for an exception variable; JavaScript uses e for an event and el for a DOM element.A locally reasonable name with no peer to harmonize with is left as-is. The rename rule above applies when peers exist; with no peer, taste alone is not grounds for renaming.
titleDiv stays as it is when no comparable sibling exists; the same name in a file with sibling files using titleBlock is renamed to match.Definitions are ordered top-down: high-level structures and public types come before the free functions that consume them.
pub struct Foo { ... } and its impls before any free function consuming Foo.Where the language requires forward declarations, they precede their use, overriding top-down ordering at the local level.
Configuration files follow each format's idiomatic grouping; within each group, entries are sorted alphabetically unless the format itself prescribes another order.
Cargo.toml orders [package] → [lib] → [dependencies] → [build-dependencies] → [features] → [profile.release] (the established Cargo convention).Every comment is in English.
A comment exists only when it adds intent the code cannot show. Required cases: a mechanical or non-obvious operation (bit-twiddling, format-specific encoding); a non-local invariant.
i += 1 # increment i — anti-pattern (stated by the code); i += 1 # wrap at frame boundary — typical (states intent).A non-trivial block of statements (≥ 30 lines, or a match/switch with heterogeneous arms) is preceded by a one-line comment naming the block's role.
match with many arms gains a one-line header naming the dispatch.A file with multiple groups of functions or methods places a one-line separator comment before each group, using the language's idiomatic single-line comment form (no decorative dashes or banners).
# Event handlers, Rust // Constructors, JavaScript // HTML helpers.No documentation comments (Rust ///, Python docstrings, JSDoc /** */) anywhere except python/pyxel/__init__.pyi. The .pyi docstrings are regenerated by scripts/generate_pyi_docstrings; do not hand-edit.
Domain conventions are uniform across all sites that follow them.
# Variables: and # Events: blocks (python/pyxel/editor/widgets/widget.py and every widget file).Every comment stands alone out of context. No self-referential gloss, no tautological phrasing.
the Pyxel API (the API of Pyxel) — anti-pattern (gloss restates the term); // explanations to aid understanding — anti-pattern (tautology).Surface formatting (indentation, line wrapping, quoting) is delegated to make format. No hand-formatting.
Cargo.toml table is not hand-reformatted.Exactly one blank line separates meaningful chunks unless make format prescribes otherwise. Runs of blank lines and blank lines inside a chunk are not used.
Each file belongs to a sibling group: same directory, same naming pattern, or shared role. Consistency is judged within the group, not against the rest of the codebase.
crates/pyxel-binding/src/*_wrapper.rs; python/pyxel/editor/widgets/*.py; python/pyxel/editor/*_editor.py; HTML pages under web/*/index.html; language JSON files under web/**/*.json.A sibling group may be an exception group: a deliberate deviation from the language's default conventions for an interface or other self-contained reason. Within an exception group, the group's internal style, its cross-file naming choices toward the mirrored interface, and the framework-level binding conventions it relies on govern.
*_wrapper.rs group mirrors the Python API (snake_case names, Python-style argument ordering, and Pyxel-historical short names like blt/cls/pset rather than the Rust-idiomatic counterparts in pyxel-core) rather than Rust conventions, and adopts the PyO3 binding conventions (#[new] for __init__, #[getter]/#[setter] for Python attributes); SDL2 call sites use C-style names; samples in python/pyxel/examples/ may simplify production patterns for educational clarity.Parallel mirrors — shapes deliberately repeated across sibling files for API symmetry or data-structure parallelism — are preserved as-is.
languages array is independently loaded by each i18n JSON.The maintainer writes in Japanese; Japanese is the source of truth for translation. Translations route through English first, then to every other language. Routing through English keeps target phrasing free of Japanese compound-noun structure.
Each target language follows its own technical-writing conventions and retains established English loanwords where the target language conventionally uses them.
Translations are produced from English; comparison (including audit) is made against the English version, not the Japanese.
"Installation des Pakets Anleitung" mirrors a Japanese compound-noun chain and is rewritten as "Paket-Installationsanleitung".The authoritative Pyxel product names are: Pyxel, Pyxel Editor, Pyxel Showcase, Pyxel Code Maker, Pyxel MML Studio, Pyxel Web Launcher, Pyxel User Examples, and Pyxel Composer. The abbreviations Pyxel Web (the web version), Pyxel MML (the MML variant), and Pyxel API (the public API) may stand in for their full forms.
Listed product names are not translated and their casing is not altered.
Pyxel Editor in every language — never pyxel editor, Pyxel-Editor, or ピクセルエディタ.Every other proper noun retains the author's chosen representation, including hyphens, spacing, and casing.
laser-jetman.html keeps its hyphen; author-titled examples are not renamed to fit a Pyxel-prefixed pattern.A descriptive label may stand in for a product name when the surrounding context establishes the reference and the label reads naturally there. Outside such contexts, the product name follows the casing rule above.
Pyxel Showcase.A CHANGELOG.md entry exists when the change carries (a) a concrete user benefit, or (b) a debugger breadcrumb a future maintainer can follow. Changes that match neither are not recorded.
cfg(...) gate); feature flag addition; internal runtime change; scoped refactor or cleanup; public API rename; release-process change.Sub-changes within a single commit are evaluated separately under the rule above.
Each entry's verb, grammar form, and object specificity match prior entries of the same change category.
Fixed entries' tense and object specificity.Each entry fits a single line of at most 80 characters; entries typically run around 60. Longer descriptions are split into sub-changes per the rule above.
Fixed Pyxel Editor color picker cursor shape across palette sizes (66 chars) fits the typical band; entries needing more detail become two short entries instead of one long line.Each entry is verified against the actual code diff, not the commit message. Commit messages may understate or misstate the diff.
Documentation wording and translation touch-ups bundle into a single summary line.
Update web titles and docs wording covers a commit touching many doc strings.Every rule above is reapplied on every revision. An earlier draft is not rubber-stamped.
This policy and its audit cover every git-tracked file that .gitattributes does not mark as binary. This policy file (docs/coding-policy.md) is in scope.
Excluded by tool-chain origin:
*.tmx (Tiled tilemap editor output)*.bdf (font tooling output)Cargo.lock and *-lock.json (package-manager lockfiles)web/styles.css (a Tailwind CSS build artifact).md files whose first line begins with <!-- This file is generated (output of scripts/generate_docs)A file's code-side aspects (structure, syntax, identifiers, non-prose elements) remain in scope even when its prose content has been handed off for separate work; the handoff covers content, not the file.
After a code change, run make format before committing.
make lint (native build) and make lint-wasm (WebAssembly build) must be warning-free at all times. The two builds use different feature sets and target environments; both must pass.
#[allow(...)] requires that the suppression itself be justified.After a code change, make test must pass before completion is claimed. A flaky failure does not waive the rule; reproduce the failure and fix the underlying cause.
The audit runs:
The audit runs as ordered phases. Each phase gates the next; the meta-rules apply throughout.
A false positive in this procedure is a fix candidate that, on closer inspection, follows the policy's intent and is therefore not modified.
Build a (file × criterion) matrix using superpowers:writing-plans, listing every cell.
pass, fix, or pending, with one line of evidence (one line per field × language for translations). Aggregate summaries are not evidence; no cell is dropped silently.e.g. line's specific patterns. A cell addressing only (b) is marked pending, not pass.(a) the file's comments contain no unstated intent; (b) grep '^\s*///' returns no match (pass), or the concrete problem (fix).Run the cross-file consistency check.
pending, not pass.*_wrapper.rs, editor widgets, web/*/index.html);python/pyxel/__init__.pyi signatures;# Variables: / # Events:) ↔ copy_var / new_var usage in python/pyxel/editor/widgets/widget.py;languages array across web/**/*.json.Verify every matrix cell by reading its evidence and assessing the verdict. Format checks (row count, regex, banned-word grep) cannot substitute. When a phase has been delegated, read the delegated work's per-cell evidence, not its overall self-verification summary.
line 12: no issue passes a regex but fails substance unless it names what was examined and why it is clean.Run the design-intent self-check on every fix candidate. A candidate that hits any of the following intents is a false positive. Standards-derived intents come first; design-derived intents follow.
cfg(...) gates);Gate completion in two stages.
superpowers:verification-before-completion to re-run Phases 1-4 against its own matrix and confirm consistency.superpowers:code-reviewer to re-audit the in-scope files against the policy, independently of the matrix. If the reviewer reports zero findings — or only a small number of judgment-call findings whose fix is not clearly net-positive — completion is gated. Otherwise the auditor incorporates the findings and a new code-reviewer cycle is run; the loop repeats until the gating condition is met.Every criterion applies to every in-scope file. Sampling, spot-check, and ad-hoc scope narrowing are not permitted, whether during the audit itself or during verification of delegated work.
.rs and .py file is checked — not "a representative sample". The same applies to verifying delegated per-cell verdicts: every cell is read, not a chosen subset.Finding imbalance is a non-execution signal. When findings concentrate in one category while structurally comparable categories return zero, the imbalance triggers a re-run on the zero-finding categories with stricter probing before proceeding.
When a phase or pair-check is delegated, the rule text is passed verbatim, the file list is passed in full, and every cross-file dependency the group must cover is named explicitly. Shortening any of these causes silent sampling.
A new concern joins an existing section before a new section is added. A new section is warranted only when no existing section fits.
Standards > Release Notes, not as a top-level section.Individual past incidents are not recorded. The lesson folds into the nearest existing rule or its example.
A section that carries an authoritative enumeration separates the enumeration from the rules: either as intro-prose stating the enumeration followed by rule-bullets, or as a rule with sub-bullets or a numbered list enumerating the items when each needs detail.
Standards > Documentation > Proper Nouns lists product names and abbreviations in its intro and uses bullets for casing rules; Standards > Source Code > Performance enumerates hot paths as sub-bullets under the rule that introduces them.Each rule may be followed by an e.g., sub-bullet that lists typical examples and, when useful, boundary cases or hypothetical anti-patterns.
e.g. line cites one or more illustrative examples; a language-specific rule names the language in its rule statement.After revising any section, the whole file is re-read and balance confirmed. Substantial growth in one part triggers a review of its structurally comparable peers for parallel gaps; minor edits do not. Proportionality is checked by section length and bullet count.