symusic-code-style

name	symusic-code-style
description	Encodes symusic's engineering taste across C++ core, nanobind bindings, and Python-facing APIs. Use when implementing or reviewing features to preserve performance-first architecture and ergonomic, predictable interfaces.
metadata	{"domain":"symusic","role":"project-specific-style-guide","scope":"implementation-and-review","output-format":"checklist-and-rationale"}

Symusic Code Style and Engineering Taste

Use this skill whenever a change touches src/, include/, py_src/, python/symusic/, or tests/.

First-Principles Guidance

1. Performance is a product feature, not an optimization pass.

   • Keep hot paths in C++ (src/, include/) and expose them through thin nanobind layers.
   • Prefer data representations that avoid repeated conversion and minimize allocation churn.

2. API symmetry beats cleverness.

   • For transformations, preserve the foo() + foo_inplace() dual interface.
   • Preserve consistent behavior across time units (Tick, Quarter, Second) and container types (Note, Track, Score).

3. Type-level correctness should be explicit at boundaries.

   • Keep time-unit semantics explicit and dispatch through well-defined factories instead of ad-hoc runtime checks.
   • Ensure Python-visible typing helpers remain informative and fail loudly on invalid construction.

4. Cross-language predictability is mandatory.

   • Python APIs should feel ergonomic, but never hide semantic differences from the C++ core.
   • Prefer deterministic behavior and clear exceptions over silent coercion.

5. Readable systems code over minimalist one-liners.

   • Favor named helper functions and local structs when they clarify non-trivial timeline/algorithm logic.
   • Document subtle invariants (time tolerance, ownership expectations, conversion assumptions) near the implementation.

Repository-Specific Style Patterns

C++ Core (include/, src/)

• Target modern C++ with explicit compile settings (C++20, no compiler extensions).
• Use project aliases and containers (i32, vec, shared, pyvec) consistently instead of mixing raw STL usage styles.
• Prefer value-semantic operations (copy, deepcopy, non-inplace transforms) and keep deep-copy semantics explicit.
• Keep equality and ordering logic structural and deterministic, including pointer-aware equality fallbacks where needed.
• For numeric timeline logic:
  • centralize tolerances,
  • avoid duplicated floating-point comparisons,
  • isolate helper predicates (close_enough, ge_or_close) and step derivation logic.

Nanobind Layer (py_src/bindings/)

• Keep module entry points compact and delegate registrations to smaller binding units.
• Prefer explicit, user-facing error messages when classes are typing placeholders or generic helpers.
• Ensure pickle/state methods and reprs are predictable and stable.
• Guard optional diagnostics (MEM_LEAK_WARNING) behind build flags rather than ad-hoc runtime branches.

Python API Layer (python/symusic/)

• Use factories to centralize dispatch across time units and core class variants.
• Keep constructors and conversion helpers straightforward; avoid hidden expensive operations.
• Raise precise exceptions (TypeError for wrong object kind, ValueError for invalid value domain).
• Keep module import side-effects intentional, short, and validated (e.g., binary path checks).

Testing and Quality Signals (tests/ + pyproject.toml)

• Keep tests behavior-focused, with clear assertions for immutability contracts and I/O round-trips.
• Treat warnings as quality regressions where configured.
• Respect existing lint philosophy: broad Ruff coverage, targeted per-file exceptions, strict pytest options.

Change Checklist Before Merge

• Did the change preserve inplace and non-inplace API symmetry where relevant?
• Are time-unit semantics (tick/quarter/second) consistent and explicitly handled?
• Are exceptions and error messages concrete and user-actionable?
• Did you avoid adding hidden work in Python wrappers that belongs in C++?
• Are tests updated for behavior and edge cases, not just happy paths?
• Are comments/docstrings in English and focused on invariants rather than restating code?

Anti-Patterns to Avoid

• Introducing convenience wrappers that blur time-unit semantics.
• Adding dependencies to solve narrowly scoped problems already covered by existing internal utilities.
• Mixing ownership styles unpredictably (raw pointers vs shared/value semantics) in core data models.
• Creating Python-side fallback implementations for logic that should remain canonical in C++.