Qzhong Cpp Style

QZhong C++ Style

Write compact, mathematically legible C++ with reusable typed components, convenient public APIs, and explicit control over storage and computation. Put flexibility in types and overloads while keeping the numerical algorithm visible as ordinary expressions and loops.

Resolve the context first

Read the target's applicable instructions, language standard, formatter, and a nearby interface and implementation. Follow explicit task/repository rules first, then the conventions of the code being edited, then these defaults. Use cuMES's explicit naming and ownership rules as defaults for new code. Do not rename established APIs or modernize an entire file just to match them.

BSplineInterpolation supports C++11; cuMES requires strict C++20. Use the target's standard. On C++20 targets, express new constraints with concepts/requires or simple traits when appropriate; preserve SFINAE and compatibility guards in older libraries. Do not add polyfills to modern targets merely because the source projects contain them.

For evidence, exceptions, or an explanation of the user's style, read references/style-evidence.md. Ordinary use does not require reopening the original projects.

Names and surface form

• Use PascalCase for types, snake_case for functions and variables, and CAPITAL_SNAKE_CASE for constants and scoped-enum enumerators in new APIs. Keep established mathematical/physics names such as psi, dpdr, rmnc, ns, nZnT, and jF. Do not expand clear formulas into verbose prose names.
• Put using val_type = T; first in the public section of scalar-templated classes/structs. Give other roles descriptive aliases such as coord_type, size_type, matrix_type, and error_type. Derive aliases from component types rather than repeating concrete types. Do not invent a scalar alias for a template with no scalar role, such as CLAP<Config>.
• Prefer trailing underscores for private data in new classes. Private helper suffixes such as build_solver_ occur frequently; follow neighboring code rather than requiring a suffix for every private function. Plain data structs can expose named fields directly.
• Use the existing .clang-format. The shared baseline is Chromium, four-space indentation, 80 columns, attached braces, and short if/loop/block bodies allowed on one line. Small accessors like size() const { return size_; } and guards like if (empty()) { return; } fit the style.
• Wrap long templates, signatures, initializer lists, and formulas with the formatter's continuation alignment. Keep T*/T& spelling and include grouping consistent with the target. Include order differs between the old libraries and cuMES; there is no universal personal include order.
• For a new project without a formatter, use assets/clang-format as a .clang-format starting point. Do not replace an existing configuration or reformat unrelated code.

Types, APIs, and decomposition

• Parameterize genuinely variable scalar types, dimensions, orders, and callable policies. Use fixed-size std::array when the shape is known at compile time. Keep one source of truth for precision and derive downstream types from it; distinct coordinate/value/accumulation types can be intentional.
• Prefer concrete composition, function templates, and callable parameters for numerical customization. Small lambdas should express the user's field formula at the call site. Use traits to derive output shape when useful. CRTP fits a shared implementation with real static specializations; it is an available technique, not a requirement for every class.
• Provide a clear core operation and a few useful convenience forms. Delegate constructors/overloads to one implementation. Examples are coordinate-array plus variadic overloads, operator() for a mathematical callable, and solve backed by solve_in_place.
• Where both access modes are useful, distinguish ordinary evaluation from an explicitly checked form such as at/derivative_at. Document preconditions; do not add duplicate checks to every layer of a numerical hot path.
• Keep configuration, raw input, reusable computation, and output representation distinguishable. Use small structs for coherent values and owning classes for reusable state. Avoid introducing interface hierarchies, factories, or extra modules without a concrete variation or ownership need.
• Header-only template libraries and small single-header utilities are natural here. Keep non-template implementation in source files when that is the target's pattern. Do not force cuMES's explicit-instantiation layout onto a standalone CPU library.

Ownership and cost

• Use values and RAII ownership. Prefer std::vector/std::array for storage, references for objects, and std::span/std::string_view for borrowed data when the language standard permits. In new host APIs, use std::optional<std::reference_wrapper<T>> for a nullable borrowed object where appropriate. Preserve iterator-range APIs in compatible libraries.
• Keep raw pointers at necessary interop/device boundaries. In CUDA code use the project's buffer/arena owners and typed views; retain d_/h_ pointer prefixes where applicable. Old pointer arithmetic in clap.h is not a model for new ownership or reflection code.
• Separate expensive setup from repeated work when reuse exists: build/factor once, solve/evaluate many times; cache coordinate-dependent work separately from changing field values. Reserve known capacities and reuse scratch where it matters. Do not add a cache or allocator without a demonstrated use.
• Pass read-only containers by const reference or view. Move owned storage into an object; use forwarding references only when forwarding serves the API. Return local values normally to allow copy elision. Preserve meaningful const&/&& overloads for reuse versus consumption.
• Keep memory layout and loop order explicit. Flat contiguous storage and dimensional wrappers recur, but BSpline Mesh is row-major and cuMES uses column-major layouts: honor the algorithm's actual contract.

Numerical implementation and diagnostics

• Write recognizable formulas and direct loops. Use short local lambdas for nearby transformations, auto for obvious or complicated derived types, and explicit scalar/index types when precision or signedness matters. Prefer named intermediates when a conditional or expression becomes hard to read; compact code need not become a dense nested ternary.
• Use const, constexpr, explicit conversions, and typed zero initialization where their meaning is useful. Keep precision conversions deliberate; do not change accumulation type or floating-point evaluation order as a style edit.
• Use compile-time checks for type/shape constraints, runtime validation for external input, and assertions for internal invariants, following the target's error mechanism. Diagnostics should identify the offending value/option and the expected condition. Do not copy old unchecked parsing behavior.
• Macros are acceptable for an existing registration DSL, configuration switch, or compatibility boundary. The preference shown by clap.h is concise typed registration at the call site; macros and byte offsets are not universal implementation requirements.
• Comment mathematical meaning, units, ordering, boundary/periodicity conventions, and non-obvious lifetime or performance decisions. Short section comments can mark algorithm stages. Use concise Doxygen documentation for public templates when neighboring code does, without narrating every statement.

Verification

Use the project's checks. For numerical changes, favor observable mathematical properties, analytic cases, residuals, or CPU-reference comparisons, including relevant precision and boundary cases. The source projects favor standalone test executables with lightweight assertions; do not introduce a test framework just for a small addition. Keep correctness checks separate from timing claims.

In cuMES, consult its current verification rules before a numerical refactor: the frozen trajectory and controller decisions can be part of correctness. Those gates, GPU-only execution, and allocation-at-startup requirements are project contracts, not universal C++ preferences.