XII Engine C++ Coding Standards and Engineering Guidelines

XII Engine

XII is a modular, cross-platform engine developed in C++23 for high-performance, real-time applications. While real-time rendering is one of its central capabilities, XII is designed to support a broader range of applications, including simulations, scientific visualization, interactive systems, and other performance-sensitive workloads.

As an engine grows, maintaining consistency across its codebase becomes increasingly important. With multiple subsystems, platform-specific implementations, shared interfaces, and contributors working on different parts of the project, seemingly small implementation decisions can have consequences far beyond the files being modified.

This raises an important question: How do we establish engineering practices that preserve correctness, performance, and maintainability without unnecessarily restricting implementation choices?

To address this, we have introduced a comprehensive set of C++ Coding Standards and Engineering Guidelines for XII Engine.

These guidelines extend beyond traditional formatting and naming conventions. They establish a common engineering philosophy for designing interfaces, managing resources, handling failures, organizing implementations, and making architectural decisions throughout the engine.

The emphasis is on several fundamental principles:

• Correctness before cleverness: Code should preserve documented invariants and communicate its behavior clearly.
• Explicit ownership and lifetime: Resource ownership, borrowing, destruction, and invalidation must be understandable and enforceable.
• Cohesive interfaces: Abstractions should represent meaningful responsibilities without exposing unnecessary implementation details.
• Cross-platform consistency: Implementations must respect shared contracts across supported platforms, compilers, and backends.
• Evidence-based optimization: Performance decisions should reflect representative workloads and measurable bottlenecks rather than speculation.
• Predictable failure handling: Expected operational failures should be communicated explicitly, without relying on C++ exceptions.
• Modern C++23 practices: Language features should improve clarity, safety, or efficiency while remaining compatible with XII’s supported toolchains.

An important consideration throughout the document is that coding standards should not become a substitute for engineering judgment. Not every abstraction is necessary, not every operation requires another layer of validation, and not every performance optimization justifies additional complexity.

Instead, the goal is to make routine engineering decisions consistent while allowing carefully justified exceptions when the requirements of a particular subsystem demand them.

The standards also introduce contributor and reviewer checklists, helping establish a consistent approach to evaluating correctness, ownership, compatibility, testing, and performance during development.

Ultimately, this initiative is about establishing a foundation for sustainable engineering as XII continues to evolve. Code should not merely work today; its responsibilities, assumptions, and constraints should remain understandable to the people who build upon it tomorrow.

The complete guidelines are available in the repository:

XII Engine - C++ Coding Standards and Engineering Guidelines

1. Core Principles

1.1 Correctness Before Cleverness

• Code MUST express the intended semantics and maintain its documented invariants on all supported platforms.
• Prefer straightforward implementations over clever solutions that obscure ownership, ordering, lifetime, or failure behavior.
• Avoid introducing generic abstractions without a concrete consumer and a clearly defined responsibility.
• Do not introduce additional states, registration layers, configuration enums, or caches without a demonstrated need.
• Make invalid states difficult to represent. Validate untrusted inputs and enforce preconditions at system boundaries.
• Operations that can legitimately fail MUST expose their failure through an explicit mechanism, such as xiiResult. XII does not use C++ exceptions for ordinary error handling.
• Callers MUST NOT silently discard failures that affect correctness.

Prefer:

xiiResult LoadConfiguration(xiiStringView sPath)
{
  xiiFileReader file;

  if (file.Open(sPath).Failed())
    return XII_FAILURE;

  return ParseConfiguration(file);
}

Avoid:

void LoadConfiguration(xiiStringView sPath)
{
  xiiFileReader file;

  file.Open(sPath); // Failure is ignored.

  ParseConfiguration(file); // May operate on an unopened file.
}

The preferred implementation makes the operation’s success or failure observable to the caller and prevents parsing when opening the file fails. It also propagates parsing failures rather than claiming success unconditionally.

Expected Failures vs. Contract Violations

Not every invalid argument warrants a xiiResult.

A distinction MUST be maintained between expected runtime failures and programming errors:

• Expected runtime failures arise during otherwise valid operations and must be handled explicitly. Examples include inaccessible files, malformed external data, unavailable network services, and resource initialization failures.
• Contract violations indicate incorrect use of an API or a violated internal invariant. These should be prevented through API design and detected using assertions or other appropriate contract-enforcement mechanisms.

For example, if a function requires a nonzero interval as part of its documented contract, and its callers are entirely under engine control, an assertion is more appropriate:

void SetFrameInterval(xiiUInt32 uiInterval)
{
  XII_ASSERT_DEV(uiInterval > 0U, "Frame interval must be greater than zero.");

  m_uiFrameInterval = uiInterval;
}

If the interval originates from an external configuration file, the value should instead be validated at the configuration boundary, where invalid input can be reported as a recoverable failure.

Error-handling requirements:

• Use xiiResult for operations where success or failure must be communicated to the caller.
• Use assertions to detect violations of documented preconditions and internal invariants.
• Do not use xiiResult as a substitute for enforcing API contracts.
• Do not return XII_SUCCESS unless the operation has fulfilled its documented success conditions.
• Do not silently ignore a failed operation when subsequent execution depends on its success.
• Propagate failures to the appropriate boundary unless the current function can meaningfully handle or recover from them.
• Do not use xiiResult when callers require structured error information beyond success or failure. Use an appropriate result type or explicit error output instead.
• C++ exceptions MUST NOT be used for ordinary error handling. Exceptions are permitted only where unavoidable within deeply isolated platform-specific implementations and MUST NOT propagate across engine API boundaries.

Guiding principle:

Expected runtime failures are values, not exceptions. Programming errors are contract violations, not ordinary runtime failures.

1.2 Make Ownership and Lifetime Visible

Ownership, lifetime, and access semantics MUST be explicit and consistent. A component should make it possible to determine who owns a resource, how long it remains valid, and under what conditions it may be accessed.

A reviewer should be able to answer:

• Creation: Who creates or acquires the object or resource?
• Ownership: Who is responsible for managing its lifetime?
• Destruction: Who destroys or releases it, and when?
• Lifetime: Can it outlive the object, subsystem, or context on which it depends?
• Invalidation: What invalidates its pointers, references, views, iterators, handles, or GPU resources?
• Concurrency: Which threads may access or modify it, and what synchronization is required?

Names, types, and interfaces SHOULD communicate these relationships without requiring callers to inspect implementation details.

Ownership Requirements

• Every dynamically managed object or resource MUST have a clearly defined owner or ownership policy.
• Prefer automatic storage and deterministic destruction where practical.
• Use RAII to associate resource acquisition with cleanup whenever ownership can be represented by object lifetime.
• Use xiiUniquePtr for exclusive dynamic ownership and xiiSharedPtr only when shared ownership is genuinely necessary.
• Use non-owning pointers, references, spans, and views for borrowed access. Their lifetime MUST NOT exceed that of the referenced storage.
• Use opaque, generation-checked handles for independently managed objects whose lifetime is controlled by a registry, manager, or subsystem.
• Do not expose owning raw pointers without an explicit and documented ownership-transfer contract.
• Avoid implicit ownership transfer, hidden lifetime extension, and unnecessary shared ownership.
• Destruction and release operations MUST preserve the owning component’s invariants, including when an operation fails.

Prefer:

class xiiDocument
{
public:
  explicit xiiDocument(xiiUniquePtr<xiiDocumentData>&& pData)
    : m_pData(std::move(pData))
  {
  }

  // Borrowed access. The reference is valid only while
  // the document and its data remain alive.
  const xiiDocumentData& GetData() const
  {
    return *m_pData;
  }

private:
  // Exclusive ownership with deterministic destruction.
  xiiUniquePtr<xiiDocumentData> m_pData;
};

Avoid:

class xiiDocument
{
public:
  explicit xiiDocument(xiiDocumentData* pData)
    : m_pData(pData)
  {
  }

  // Ownership and lifetime are ambiguous.
  xiiDocumentData* GetData()
  {
    return m_pData;
  }

private:
  xiiDocumentData* m_pData;
};

The preferred implementation makes exclusive ownership explicit through the type system. The document controls the lifetime of its data, and consumers receive borrowed access without acquiring ownership.

The avoided implementation leaves callers uncertain whether the pointer is owned, borrowed, transferred, or expected to be deleted elsewhere.

Handles and Resource Lifetimes

Handles are appropriate when resources are managed independently of the objects that reference them.

• Handles MUST NOT imply ownership unless explicitly documented.
• A handle MUST be validated before accessing its associated resource whenever its validity cannot be guaranteed by the calling contract.
• Reusable handle slots SHOULD employ generation counters or equivalent mechanisms to detect stale references.
• Resource destruction MUST invalidate the corresponding logical handle according to the subsystem’s documented lifetime rules.
• Do not expose internal resource pointers when a handle-based interface is required to preserve lifetime or synchronization guarantees.
• Avoid using handles for objects whose lifetime is already clearly and safely expressed through ordinary value or reference semantics.

A generation-checked handle protects against stale logical references but does not automatically guarantee that the underlying resource remains alive during concurrent access.

Likewise, GPU resource lifetime must account for asynchronous execution. Releasing a logical handle does not necessarily mean the underlying allocation can be destroyed immediately if submitted GPU work still references it.

Borrowed Access and Invalidation

Non-owning access MUST have a clearly established validity period.

• Returned pointers, references, spans, and views MUST NOT outlive their backing storage.
• Container mutation, relocation, resource replacement, and subsystem shutdown MUST be considered when establishing validity guarantees.
• APIs SHOULD avoid returning references to internal storage when subsequent operations may invalidate them unexpectedly.
• Do not retain borrowed references across asynchronous operations unless their lifetime is explicitly guaranteed.
• Borrowed access MUST NOT be mistaken for thread-safe access. Synchronization requirements remain independent of ownership.

Concurrency and Destruction

Ownership and thread safety are separate concerns.

• Shared ownership does not imply synchronized access to mutable state.
• Components MUST document concurrent access restrictions when they cannot be inferred from the API contract.
• Destruction MUST NOT race with active operations that access the object or resource.
• Asynchronous operations MUST establish how their dependencies remain valid until completion.
• Deferred destruction SHOULD be used when resources remain referenced by queued operations, background tasks, or GPU submissions.
• Synchronization and lifetime guarantees MUST be enforced by the responsible subsystem rather than delegated implicitly to unrelated callers.

Guiding principle:

Ownership determines who is responsible for a resource. Lifetime determines when it is valid. Access rules determine who may use it and under what conditions. These contracts must remain explicit, independently enforceable, and consistent throughout XII.

1.3 Small Interfaces, Cohesive Implementations

Classes, services, and modules MUST have clearly defined responsibilities and expose only the functionality required by their consumers. Public interfaces should describe supported operations rather than reveal implementation details.

• Follow the principle of high cohesion and low coupling. Group functionality that shares a coherent responsibility, and separate functionality that changes for unrelated reasons.
• Expose the smallest public API that satisfies demonstrated use cases. Do not add methods, overloads, or extension points for hypothetical requirements.
• Keep internal storage, data structures, synchronization mechanisms, and implementation-specific state private unless explicitly required by a documented contract.
• Prefer intention-revealing operations over exposing mutable internal state.
• Maintain invariants within the component that owns them. Callers MUST NOT be required to understand or preserve another component’s internal invariants.
• Avoid unnecessary manager classes, service layers, registries, and wrapper abstractions. Introduce them only when they establish meaningful ownership, coordination, or architectural boundaries.
• Do not fragment cohesive functionality into multiple classes merely to satisfy an arbitrary class-size or method-count restriction.
• Prefer stable interfaces that permit implementations to evolve without requiring changes throughout the codebase.

Prefer:

class xiiResourceRegistry
{
public:
  [[nodiscard]] xiiResourceHandle RegisterResource(xiiStringView sPath);

  void UnregisterResource(xiiResourceHandle hResource);

  [[nodiscard]] bool IsRegistered(xiiResourceHandle hResource) const;

private:
  xiiHashTable<xiiResourceHandle, ResourceEntry> m_Resources;
};

Avoid:

class xiiResourceRegistry
{
public:
  // Exposes implementation details and permits external mutation.
  xiiHashTable<xiiResourceHandle, ResourceEntry>& GetResources();

  // Callers must understand and maintain internal invariants.
  void RebuildResourceIndices();
};

The preferred interface allows the registry to control resource registration, removal, and lookup without exposing its underlying container or requiring callers to maintain its internal consistency.

The implementation can subsequently replace its hash table, introduce synchronization, or change its indexing strategy without affecting consumers.

Abstraction Boundaries

An abstraction should exist because it establishes a useful boundary, not merely because it reduces the apparent complexity of an individual implementation.

Before introducing a new interface, class, or service, consider:

• Responsibility: Does the abstraction own a coherent responsibility?
• Consumers: Is there a concrete consumer that benefits from the abstraction?
• Invariants: Does the abstraction protect meaningful invariants or ownership boundaries?
• Coupling: Does it reduce dependencies, or merely relocate them?
• Extensibility: Is extension genuinely required, or is the abstraction speculative?
• Complexity: Does the abstraction simplify the overall system rather than only the code immediately surrounding it?

A small public interface does not necessarily imply a small implementation. Complex internal algorithms and data structures are acceptable when they are necessary to fulfill a clearly defined responsibility.

Conversely, a class with few methods is not automatically cohesive if those methods address unrelated concerns.

Guiding principle:

Expose capabilities, not implementation details. Abstractions should protect invariants, clarify ownership, and reduce coupling without introducing unnecessary indirection.

1.4 Think Across Engine Boundaries

XII is a modular, multi-platform engine whose components operate within a shared architectural and runtime environment. Changes to one subsystem can affect other modules, platform implementations, plugins, tools, and applications, even when those dependencies are not immediately visible.

Changes MUST be evaluated against the contracts of the affected subsystems, not merely the compilation or correctness of the modified source file.

• Consider the full dependency chain before modifying shared interfaces, data structures, resource representations, or execution semantics.
• Preserve module boundaries and dependency direction. Lower-level modules MUST NOT acquire dependencies on higher-level modules merely to accommodate a local implementation.
• Prefer changes at the layer that owns the relevant responsibility. Do not introduce workarounds in dependent modules when the underlying issue belongs to a shared abstraction.
• Avoid coupling platform-independent functionality to a particular operating system, graphics API, compiler, or hardware architecture.
• Changes to public interfaces MUST account for existing consumers, including plugins, tools, scripting interfaces, and external integrations.
• Changes to shared behavior MUST preserve documented invariants across all supported platforms and configurations.
• Do not introduce cross-module dependencies, initialization requirements, or global state without a demonstrated architectural need.

Compatibility Requirements

Compatibility extends beyond source-level compilation. Depending on the affected subsystem, changes may influence binary interfaces, serialized data, runtime behavior, resource lifetimes, and externally consumed formats.

The following changes MUST receive compatibility consideration:

• Public headers and exported symbols: Function signatures, symbol visibility, type layouts, calling conventions, and binary compatibility.
• Enums and flags: Numeric values, underlying types, bit assignments, serialization mappings, and assumptions made by external consumers.
• Handles and resource identifiers: Validity rules, generation semantics, ownership, lifetime, and compatibility with existing resource managers.
• Reflection and type registration: Type names, properties, metadata, inheritance relationships, versioning, and registration behavior.
• Serialization and binary formats: Schema changes, field ordering, versioning, backward compatibility, and migration requirements.
• Shaders and GPU interfaces: Resource bindings, constant-buffer layouts, shader permutations, pipeline interfaces, and backend-specific restrictions.
• Plugin interfaces: Loading, initialization, shutdown, exported functionality, and compatibility across module boundaries.
• Threading and synchronization: Execution ordering, thread affinity, shared-state access, and CPU/GPU synchronization guarantees.
• Build configuration: Conditional compilation, feature flags, compiler differences, static and dynamic linking, and platform-specific dependencies.

Compatibility requirements MUST be assessed according to the documented contract of the affected interface. Not every internal implementation change requires backward compatibility, but changes to persistent formats or externally consumed interfaces must not silently invalidate existing consumers.

Platform and Backend Independence

Platform-independent modules MUST express behavior through abstractions that can be implemented consistently across supported backends.

• Do not expose backend-specific types through platform-independent interfaces unless the interface explicitly represents a native interoperability boundary.
• Do not assume that behavior guaranteed by one platform or graphics API is universally supported.
• Backend implementations MUST preserve the common interface’s documented semantics or explicitly report unsupported functionality.
• Optional functionality SHOULD be represented through capability queries or existing feature mechanisms rather than assumptions about the active backend.
• Do not introduce platform-specific branches into shared code when the behavior belongs in a platform implementation.
• Consider differences in memory alignment, endianness, pointer size, synchronization, filesystem behavior, and compiler support where relevant.

An implementation that works on one backend is not necessarily correct across the engine.

Dependency and Change Propagation

Changes SHOULD remain localized to the component that owns the affected responsibility.

When a modification requires updates across multiple modules, determine whether the change represents:

1. A legitimate evolution of a shared contract.
2. An implementation detail that has leaked across abstraction boundaries.
3. An unnecessary dependency or architectural coupling.
4. A missing responsibility in an existing subsystem.

Do not introduce additional abstraction layers solely to prevent every change from propagating. Some coordinated changes are legitimate and preferable to maintaining unnecessary compatibility mechanisms.

Conversely, repeated changes across unrelated consumers may indicate that an implementation detail has been exposed too broadly.

Validation Across Boundaries

Validation MUST reflect the scope and potential impact of the change.

• Compile and test the directly affected module and its relevant dependents.
• Verify supported platform and backend configurations when modifying shared or platform-sensitive functionality.
• Test affected resource lifetimes, initialization sequences, shutdown paths, and error-handling behavior.
• Validate reflection and serialization compatibility when modifying reflected types or persistent data.
• Verify shader compilation, resource binding compatibility, and pipeline behavior when changing GPU-facing interfaces.
• Consider existing plugins, tools, and applications that depend on the modified contract.
• Update relevant tests and documentation whenever observable behavior or public contracts change.

A successful local build is necessary but not sufficient evidence of correctness for changes that affect shared contracts.

Where complete cross-platform or cross-backend validation is impractical, the limitations SHOULD be documented, and the unverified configurations identified during review.

Guiding principle:

A change is correct only when it preserves the intended contracts of every affected boundary. Local correctness must not come at the expense of system-wide consistency, portability, or maintainability.

1.5 Optimize From Evidence

Performance is a fundamental requirement of XII, but optimization MUST be guided by measurable evidence, representative workloads, and an understanding of the underlying system.

Correctness, maintainability, and performance are complementary engineering goals. Code should be designed efficiently from the outset without introducing unnecessary complexity in pursuit of unverified performance improvements.

• Establish correctness before optimizing. An implementation that produces incorrect results more quickly is not an improvement.
• Prefer efficient algorithms, appropriate data structures, and predictable memory access patterns over low-level optimizations with negligible measurable benefit.
• Use profiling data, allocation measurements, benchmarks, and representative workloads to identify genuine bottlenecks.
• Do not sacrifice clarity, safety, or architectural boundaries for speculative performance gains.
• Conversely, do not disregard allocations, virtual dispatch, cache misses, synchronization overhead, or unnecessary data movement in demonstrated hot paths.
• Consider performance across the entire operation rather than optimizing isolated instructions without accounting for their broader effects.
• Performance-sensitive implementations SHOULD document non-obvious optimization decisions and the assumptions on which they depend.
• Optimizations MUST NOT introduce undefined behavior, violate ownership contracts, or compromise correctness across supported platforms.

Algorithmic Efficiency Before Micro-Optimization

Algorithmic complexity and data representation generally have greater consequences than isolated instruction-level improvements.

• Select algorithms based on expected input sizes, access patterns, and computational requirements.
• Consider both asymptotic complexity and practical costs, including allocation overhead, memory locality, branching, and synchronization.
• Prefer contiguous storage when access patterns benefit from spatial locality and stable addresses are not required.
• Avoid repeated computations, allocations, and conversions when their results can be reused safely and meaningfully.
• Do not introduce caches without considering invalidation, memory consumption, synchronization, and maintenance costs.
• Avoid unnecessary abstraction overhead in performance-critical paths, but do not assume that abstraction inherently prevents optimization.

Prefer:

void UpdateParticles(xiiArrayPtr<Particle> particles, float fDeltaTime)
{
  for (Particle& particle : particles)
  {
    particle.m_vPosition += particle.m_vVelocity * fDeltaTime;
  }
}

Avoid:

void UpdateParticles(xiiArrayPtr<Particle*> particles, float fDeltaTime)
{
  for (Particle* pParticle : particles)
  {
    // Unnecessary indirection if particles can be stored contiguously.
    pParticle->m_vPosition += pParticle->m_vVelocity * fDeltaTime;
  }
}

When particles have value semantics and do not require stable individual addresses, contiguous storage can improve memory locality, reduce allocation overhead, and simplify ownership.

Pointer-based storage remains appropriate when object identity, polymorphism, stable addresses, or independent lifetimes are required. The preferred representation depends on the actual contract and workload.

Memory Allocation and Data Locality

Memory management is an important performance consideration, particularly in frequently executed systems.

• Avoid unnecessary dynamic allocations in established hot paths.
• Prefer reusing existing storage when doing so does not complicate ownership or introduce excessive retained memory.
• Reserve container capacity when the expected element count is known and repeated growth would be costly.
• Consider cache locality, memory fragmentation, alignment, and access patterns when selecting data structures.
• Avoid unnecessary copies of large objects, but do not replace inexpensive value semantics with pointer indirection without justification.
• Prefer stack allocation for small, bounded temporary objects when their lifetime and size make it appropriate.
• Use custom allocators, memory pools, or arenas only when their benefits justify the additional complexity and lifetime constraints.

Allocation count alone is not a sufficient performance metric. Allocation size, frequency, lifetime, contention, and locality can be equally important.

Dispatch and Abstraction Costs

Abstractions SHOULD be evaluated according to their actual runtime costs rather than assumptions about their implementation.

• Virtual dispatch is acceptable when runtime polymorphism serves a meaningful architectural purpose.
• Avoid repeated indirect calls in proven hot loops when a simpler dispatch strategy provides a measurable improvement.
• Prefer compile-time dispatch where the set of operations is known and the resulting code remains manageable.
• Do not replace clear interfaces with complex template machinery solely to eliminate unmeasured dispatch overhead.
• Consider the effects of inlining, instruction-cache pressure, code size, and compiler optimization when evaluating alternatives.

Eliminating an individual virtual call does not necessarily improve overall performance if the surrounding computation is dominated by memory access, synchronization, or other costs.

Concurrency and Synchronization

Parallel execution MUST be evaluated in terms of useful throughput, scheduling overhead, and synchronization requirements.

• Do not assume that additional threads or tasks automatically improve performance.
• Minimize unnecessary contention, blocking, and shared mutable state in performance-critical systems.
• Prefer clearly defined ownership and data partitioning over introducing synchronization around poorly structured shared state.
• Consider lock contention, atomic operations, memory ordering, false sharing, and task scheduling overhead where measurements indicate their relevance.
• Avoid excessively fine-grained parallelism when scheduling and coordination costs exceed useful computation.
• Synchronization optimizations MUST preserve the required memory-ordering and visibility guarantees.
• Do not introduce lock-free algorithms solely because they appear faster. Their correctness and performance must be demonstrated under representative contention.

CPU and GPU Performance

Graphics and heterogeneous computing workloads require consideration of both CPU and GPU execution costs.

• Distinguish CPU-side submission overhead from GPU execution time when identifying rendering bottlenecks.
• Measure synchronization stalls, resource transitions, memory transfers, and command submission overhead where applicable.
• Avoid unnecessary CPU/GPU synchronization, particularly operations that force either processor to wait for work that could otherwise proceed asynchronously.
• Consider resource lifetime, memory residency, bandwidth, occupancy, and execution dependencies when optimizing GPU workloads.
• Do not assume that reducing the number of API calls or render passes necessarily improves performance.
• Evaluate optimizations across supported graphics backends and representative hardware configurations when backend behavior may differ.

Reducing CPU overhead is not necessarily beneficial if the change increases GPU execution time, memory consumption, synchronization cost, or frame latency.

Benchmarking and Profiling

Performance claims SHOULD be supported by reproducible measurements.

• Establish a baseline before implementing a performance optimization.
• Profile representative workloads rather than relying exclusively on synthetic microbenchmarks.
• Use appropriate tools to distinguish CPU execution time, GPU execution time, memory usage, allocation behavior, and synchronization overhead.
• Measure both typical and worst-case behavior when latency or frame-time consistency is important.
• Account for warm-up effects, caching, compiler optimization settings, background activity, and measurement variability.
• Compare results under equivalent conditions, including build configuration, hardware, input data, and execution environment.
• Repeat measurements sufficiently to distinguish meaningful improvements from noise.
• Include correctness validation to ensure the optimized implementation preserves the original behavior.

For real-time workloads, average execution time alone is insufficient. Frame-time variance, latency spikes, and worst-case execution behavior may be more important than peak throughput.

Optimization Trade-offs

Performance optimizations frequently introduce trade-offs between execution time, memory consumption, code size, complexity, and portability.

Before accepting a non-trivial optimization, consider:

1. Evidence: Has a measurable bottleneck been identified?
2. Impact: Does the optimization meaningfully improve the target workload?
3. Correctness: Are all documented invariants and observable semantics preserved?
4. Complexity: Is the additional implementation and maintenance cost justified?
5. Portability: Does the improvement hold across the relevant platforms and hardware?
6. Regression risk: Could the optimization degrade other workloads or execution paths?
7. Verification: Can the performance improvement be reproduced and tested?

An optimization that substantially complicates an implementation for an insignificant improvement SHOULD be rejected unless the improvement satisfies a documented performance requirement.

Conversely, additional implementation complexity may be justified when measurements demonstrate a meaningful improvement in a critical subsystem.

Guiding principle:

Design for efficiency, measure before optimizing, and preserve correctness throughout. Performance improvements should solve demonstrated problems rather than anticipated ones.

2. Source Layout and Formatting

2.1 Formatting Authority

Consistent source formatting is essential for readability, maintainability, and effective code review. XII establishes formatting rules through repository-level configuration files to ensure that source code remains uniform across contributors, development environments, and supported platforms.

The root .clang-format file is the authoritative source for C++ formatting rules that can be expressed by ClangFormat. The repository’s .editorconfig governs applicable editor settings, including indentation, whitespace, line endings, and character encoding.

Contributors MUST NOT introduce personal formatting conventions that conflict with these configurations.

Formatting Requirements

• Modified C++ source code MUST be formatted using the repository’s configured ClangFormat rules and compatible formatter version.
• The repository’s .clang-format configuration MUST NOT be overridden through personal editor settings or alternative formatting configurations.
• Formatting MUST remain consistent regardless of the editor, IDE, operating system, or development environment used.
• Contributors MUST NOT manually introduce alignment, indentation, or spacing conventions that conflict with the configured formatter.
• Existing brace placement, declaration layout, spacing, and naming conventions SHOULD be preserved where they are not governed by automated formatting.
• Formatting changes MUST NOT alter program semantics, preprocessor behavior, or documented interfaces.
• Source files MUST NOT contain trailing whitespace, inconsistent indentation, unintended mixed line endings, or unresolved merge conflict markers.
• Source text SHOULD use UTF-8 encoding unless a specific file format, platform interface, or toolchain requires otherwise.
• File encodings and line-ending conventions MUST NOT be changed without considering repository configuration and tooling compatibility.

Scope of Formatting Changes

Formatting changes MUST remain proportional to the scope of the work being performed.

• Functional pull requests MUST NOT include unrelated repository-wide or mass formatting changes.
• Contributors SHOULD format only the files or code regions affected by their modifications when formatting an entire file would introduce substantial unrelated changes.
• Existing formatting inconsistencies outside the scope of a change SHOULD be addressed separately unless correcting them is necessary for the current modification.
• Dedicated formatting changes MUST be separated from functional changes whenever practical.
• Formatting-only changes MUST NOT intentionally modify program behavior.

Keeping formatting changes separate from functional changes reduces review noise, preserves meaningful version-control history, and simplifies regression analysis.

Automated Formatting and Tooling

Automated formatting SHOULD be integrated into the development workflow to reduce manual effort and prevent inconsistencies.

• Editors and IDEs SHOULD be configured to discover and use the repository’s .clang-format and .editorconfig files.
• Contributors SHOULD use automated formatting before submitting changes for review.
• Continuous integration MAY enforce formatting compliance using the repository’s approved formatter configuration.
• Automated formatting tools MUST NOT silently rewrite unrelated source files as part of a functional change.
• Formatter upgrades or modifications to formatting configuration MUST be reviewed independently because they may affect a substantial portion of the codebase.
• Generated source files SHOULD be formatted consistently when supported by their generators. Contributors MUST NOT manually format generated output when those changes would be overwritten by regeneration.

Where automated formatting cannot express a particular convention, contributors SHOULD follow the established style of the surrounding code.

Formatting Exceptions

Certain source constructs may require deliberate formatting to preserve readability, compatibility, or tool-generated structure.

Examples include:

• Preprocessor macros whose formatting affects continuation or expansion behavior.
• Generated code whose layout is controlled by an external generator.
• Platform-specific declarations requiring prescribed syntax or layout.
• Embedded source languages, shader code, or structured data that follow separate formatting rules.
• Tables or aligned declarations where automated formatting would significantly reduce readability.

Exceptions MUST be narrowly scoped and justified by a concrete technical requirement.

ClangFormat suppression directives SHOULD NOT be introduced merely to preserve personal formatting preferences. Where suppression is necessary, it SHOULD encompass the smallest practical region.

Guiding principle:

Formatting is a repository-wide contract, not an individual preference. Automate consistency, minimize unrelated changes, and keep code reviews focused on semantics rather than presentation.

2.2 Braces and Indentation

Consistent brace placement and indentation are essential for expressing control flow clearly and preventing ambiguity. XII follows Allman-style braces for class definitions, function definitions, and multi-line control blocks, with indentation and spacing governed by the repository’s .clang-format configuration.

Braces and indentation MUST make the logical structure of the code immediately apparent without requiring readers to infer statement ownership.

General Requirements

• Class, struct, namespace, function, and multi-line control-flow definitions MUST follow the brace placement prescribed by .clang-format.
• Use consistent indentation according to the repository’s configured indentation width.
• Opening and closing braces MUST clearly delimit the scope they introduce.
• Closing braces MUST align with their corresponding declarations or control statements.
• Do not introduce unnecessary nesting when guard clauses or early returns provide a clearer implementation.
• Braces MUST NOT be omitted when doing so introduces ambiguity or makes the control flow difficult to follow.
• Do not manually align statements or braces in ways that conflict with the repository’s formatter.

Prefer:

class xiiResourceRegistry
{
public:
  void Clear()
  {
    m_Entries.Clear();
  }

private:
  xiiDynamicArray<xiiUInt32> m_Entries;
};

The structure makes access control, function scope, and member declarations immediately distinguishable.

Single-Statement Control Blocks

Braces MAY be omitted for simple, single-statement conditions and loops when the resulting control flow remains unambiguous.

This convention is particularly appropriate for guard clauses, validation checks, and early returns.

Prefer:

xiiResult Initialize(xiiDevice* pDevice)
{
  if (pDevice == nullptr)
    return XII_FAILURE;

  if (m_bInitialized)
    return XII_SUCCESS;

  return InitializeResources(pDevice);
}

Braces SHOULD be omitted only when all of the following conditions are satisfied:

• The controlled body contains exactly one statement.
• The statement remains readable without additional scope.
• No ambiguity exists regarding control-flow ownership.
• The condition and its body are sufficiently simple to understand immediately.
• Omitting braces is consistent with the surrounding code and formatter configuration.

Braces SHOULD be introduced when the controlled statement becomes more complex or when additional statements are added.

Multi-Statement Control Blocks

Braces MUST be used when a conditional branch or loop contains multiple statements.

Prefer:

if (bNeedsRebuild)
{
  ResetResources();
  RebuildResources();
  UpdateResourceBindings();
}

Avoid:

if (bNeedsRebuild)
  ResetResources();
  RebuildResources();
  UpdateResourceBindings();

In the avoided implementation, only the first statement is controlled by the condition. The remaining statements execute unconditionally, potentially violating the intended control flow.

Braces are therefore a correctness mechanism as well as a formatting convention.

Nested Conditions and Ambiguous Control Flow

Nested conditionals MUST NOT rely on implicit else association.

Avoid:

if (bVisible)
  if (bReady)
    Process();
  else
    LogNotReady();

The else belongs to the innermost unmatched if, which may not reflect the intended behavior.

Prefer:

if (bVisible)
{
  if (bReady)
  {
    Process();
  }
  else
  {
    LogNotReady();
  }
}

Where possible, simplify nested conditions using guard clauses or combined predicates.

Prefer when equivalent:

if (!bVisible)
  return;

if (!bReady)
{
  LogNotReady();
  return;
}

Process();

Early returns SHOULD be preferred when they reduce nesting without obscuring cleanup, resource ownership, or control-flow requirements.

Conditional Branches

For if, else if, and else chains, braces SHOULD be applied consistently across branches when any branch requires a multi-statement body.

Prefer:

if (state == xiiResourceState::Ready)
{
  ProcessResource();
  UpdateStatistics();
}
else if (state == xiiResourceState::Pending)
{
  QueueResource();
}
else
{
  LogResourceFailure();
}

Avoid mixing braced and unbraced branches when doing so makes the structure less predictable.

Simple conditional chains MAY omit braces where permitted by the formatter and where every branch remains unambiguous.

Loops and Iteration

Loop bodies follow the same rules as conditional statements.

Braces MAY be omitted for simple, single-statement loops.

Prefer:

for (xiiUInt32 uiIndex = 0; uiIndex < m_Entries.GetCount(); ++uiIndex)
  ProcessEntry(m_Entries[uiIndex]);

Braces MUST be used for multi-statement loop bodies.

Prefer:

for (xiiUInt32 uiIndex = 0; uiIndex < m_Entries.GetCount(); ++uiIndex)
{
  ResourceEntry& entry = m_Entries[uiIndex];

  if (!entry.m_bActive)
    continue;

  ProcessEntry(entry);
  UpdateStatistics(entry);
}

Loop bodies SHOULD remain focused and avoid excessive nesting. Where iteration logic becomes difficult to follow, consider extracting a cohesive operation into a separate function.

Scope and Lifetime

Braces also define lexical scope and therefore influence object lifetime and deterministic destruction.

• Introduce explicit scopes when a shorter lifetime is necessary for correctness, synchronization, or resource management.
• Do not introduce additional scopes merely for visual grouping when they serve no meaningful purpose.
• Variables SHOULD be declared in the narrowest practical scope that satisfies their intended use.
• RAII-managed resources MUST remain alive for the entire duration of operations that depend on them.
• Scope boundaries MUST NOT accidentally invalidate borrowed references, pointers, views, or iterators.

Prefer:

{
  XII_LOCK(m_Mutex);
  UpdateSharedState();
}

// The lock is released before performing independent work.
ProcessPendingTasks();

An explicit scope is justified here because it determines the duration of synchronization rather than serving as a purely stylistic grouping.

Maintenance and Review

Code structure SHOULD remain easy to modify without introducing accidental changes in control flow.

• When adding statements to an unbraced control block, introduce braces before expanding the body.
• Review nested branches carefully when modifying conditions or adding else clauses.
• Avoid formatting that visually suggests a statement belongs to a scope when it does not.
• Do not rely on indentation alone to express control flow; C++ semantics are determined by statement structure and braces.
• Prefer restructuring deeply nested logic over adding layers of braces that obscure the operation’s intent.

Guiding principle:

Braces define control flow, scope, and lifetime. Use them consistently to eliminate ambiguity, preserve correctness, and make the structure of an implementation immediately understandable.

2.3 Alignment and Spacing

Consistent alignment and spacing improve readability by making relationships between declarations, expressions, and operations immediately apparent. Formatting MUST follow the repository’s .clang-format configuration, which determines the exact alignment and spacing rules.

Alignment should clarify related code without introducing unnecessary whitespace or making maintenance more difficult.

General Requirements

• Use consistent spacing around operators, assignments, declarations, and expressions as prescribed by the repository’s formatter.
• Related declarations and initializations MAY be aligned when doing so improves readability and is supported by the formatter.
• Do not manually introduce alignment that conflicts with automated formatting.
• Avoid aligning unrelated statements or declarations across large regions of code.
• Use blank lines to separate logically distinct operations, not individual statements without meaningful separation.
• Do not introduce excessive vertical whitespace that unnecessarily fragments cohesive implementations.
• Preserve consistent spacing within classes, functions, namespaces, and control-flow structures.

Prefer:

xiiUInt32 m_uiFrameIndex = 0U;
xiiUInt32 m_uiPassCount  = 0U;
bool      m_bActive      = false;

Related member declarations may benefit from alignment because their types, names, and initializers form a compact logical group.

Avoid:

xiiUInt32                    m_uiFrameIndex = 0U;
xiiUInt32                    m_uiPassCount  = 0U;

bool                         m_bActive      = false;

// Unrelated declarations should not dictate alignment.
xiiUniquePtr<xiiResourceData> m_pResourceData;

Alignment SHOULD NOT introduce large amounts of whitespace merely to maintain common columns across unrelated declarations.

Logical Spacing

Blank lines SHOULD communicate transitions between logically distinct operations.

Prefer:

const xiiUInt32 uiWidth  = descriptor.m_uiWidth;
const xiiUInt32 uiHeight = descriptor.m_uiHeight;

if (uiWidth == 0U || uiHeight == 0U)
  return XII_FAILURE;

const xiiUInt64 uiPixelCount = static_cast<xiiUInt64>(uiWidth) * uiHeight;

AllocateStorage(uiPixelCount);
InitializeStorage();

Avoid inserting blank lines after every declaration or statement when those statements form one cohesive operation.

Similarly, do not compress unrelated stages of an implementation into a single uninterrupted block.

Guiding principle:

Alignment should reveal relationships, and whitespace should reveal structure. Neither should introduce unnecessary complexity or compete with automated formatting.

2.4 Statement Structure

Statements MUST communicate their purpose clearly and avoid unnecessary combinations of declarations, assignments, conditions, and side effects.

Prefer explicit operations and predictable control flow over compact expressions that require additional interpretation.

General Requirements

• Declare one independently meaningful variable per statement.
• Initialize variables at the point of declaration whenever practical.
• Prefer declarations in the narrowest scope that satisfies their intended use.
• Avoid assignment inside conditional expressions unless it materially improves clarity.
• Use parentheses to clarify complex boolean expressions, particularly when mixing logical operators.
• Do not combine unrelated side effects into a single statement.
• Avoid comma expressions when ordinary sequential statements communicate the same behavior more clearly.
• Prefer early returns for invalid inputs and unmet preconditions when they simplify control flow.
• Do not rely on implicit operator precedence when an expression could reasonably be misinterpreted.
• Do not introduce temporary variables that merely rename an expression without improving readability, correctness, or reuse.

Declarations and Initialization

Prefer:

const xiiUInt32 uiWidth  = descriptor.m_uiWidth;
const xiiUInt32 uiHeight = descriptor.m_uiHeight;

if (uiWidth == 0U || uiHeight == 0U)
  return XII_FAILURE;

Avoid:

xiiUInt32 uiWidth, uiHeight;

uiWidth = descriptor.m_uiWidth;
uiHeight = descriptor.m_uiHeight;

Separate declarations make initialization and variable lifetime easier to inspect.

Multiple declarations in a single statement SHOULD be avoided when their variables have independent meanings or initialization requirements.

Assignments and Conditions

Assignments within conditions SHOULD be avoided when separating the operations improves clarity.

Prefer:

xiiResource* pResource = FindResource(sName);

if (pResource == nullptr)
  return XII_FAILURE;

ProcessResource(*pResource);

Avoid:

if (xiiResource* pResource = FindResource(sName))
  ProcessResource(*pResource);
else
  return XII_FAILURE;

The second form is valid C++, but the first makes lookup, validation, and subsequent processing distinct operations.

C++17-style conditional initializers MAY be used when their scope restriction provides a clear benefit and the condition remains straightforward.

Complex Expressions

Complex conditions SHOULD be structured so that their intent is immediately understandable.

Prefer:

const bool bRequiresUpdate = bDirty || bForceUpdate;
const bool bCanUpdate      = bInitialized && !bPendingDestruction;

if (bRequiresUpdate && bCanUpdate)
  UpdateResource();

Avoid:

if ((bDirty || bForceUpdate) && bInitialized && !bPendingDestruction)
  UpdateResource();

Named intermediate predicates are appropriate when they clarify domain-specific meaning, are reused, or make a complex condition easier to verify.

Do not introduce intermediate variables for every simple expression.

Side Effects and Evaluation Order

Statements with side effects MUST preserve clear and predictable evaluation semantics.

Prefer:

UpdateResourceState();
NotifyDependents();
RecordStatistics();

Avoid:

UpdateResourceState(), NotifyDependents(), RecordStatistics();

Avoid expressions that modify and access shared state through multiple operands when their evaluation order is unclear or dependent on subtle language rules.

Guiding principle:

Each statement should express a clear operation. Prefer explicit initialization, understandable conditions, and predictable evaluation over unnecessary compactness.

2.5 Includes and Whitespace

Header dependencies MUST be explicit, organized, and consistent with XII’s module architecture.

Include ordering should communicate the relationship between the current translation unit, its module, and its dependencies while preserving independent compilation and minimizing unnecessary coupling.

General Requirements

• Use one #include directive per line.
• Include only headers required by the declarations or implementation.
• Prefer the narrowest appropriate header rather than importing a broad subsystem header unnecessarily.
• Do not rely on transitive includes for types, macros, or functions directly required by the current file.
• Public headers MUST be self-contained and compile independently when included in a valid translation unit.
• Public headers MUST NOT depend on a precompiled header to provide missing declarations or dependencies.
• Avoid circular header dependencies. Use forward declarations where appropriate and where complete type information is not required.
• Do not use relative paths to navigate between module include directories when the repository’s module-qualified include paths are available.
• Preserve the established include ordering and grouping conventions.
• Separate meaningful include groups with a single blank line.
• Do not introduce unnecessary blank lines within a cohesive include group.

Header Files

Header files MUST begin with the repository’s required license and copyright notice, followed by #pragma once.

For headers belonging to a dynamically linked module, the module’s DLL.h MUST be the first included header immediately following #pragma once.

No other include directive or forward declaration should appear between #pragma once and the module’s DLL.h.

Prefer:

#pragma once

#include <GraphicsCore/GraphicsCoreDLL.h>

#include <Foundation/Containers/DynamicArray.h>
#include <Foundation/Strings/StringView.h>
#include <Foundation/Types/Result.h>

#include <GraphicsFoundation/Resources/Resource.h>

The module’s DLL.h provides the export and import definitions required by its public interfaces.

It MUST NOT be omitted from headers that rely on module export macros merely because another included header happens to provide those definitions transitively.

Headers for modules that do not use a DLL export header are exempt from this requirement.

Implementation Files

C++ implementation files MUST begin with the repository’s required license and copyright notice. For implementation files that use a module precompiled header, the corresponding module PCH MUST be the first include immediately following that notice, before all other header dependencies.

Other dependencies SHOULD then be grouped according to their architectural relationship.

A typical implementation file follows this structure:

1. Module precompiled header.
2. Required headers from lower-level modules.
3. Headers from the current module.
4. Additional dependencies from other permitted modules or application-specific components.

Prefer:

#include <GraphicsCore/GraphicsCorePCH.h>

#include <Foundation/Containers/IdTable.h>
#include <Foundation/Threading/Mutex.h>

#include <GraphicsFoundation/Resources/Resource.h>

#include <GraphicsCore/Pipeline/RenderGraphManager.h>
#include <GraphicsCore/Pipeline/RenderGraphResourceCache.h>

The ordering of include groups MUST NOT be interpreted as permission to introduce architectural dependencies that violate the module dependency graph.

Where project-specific conventions establish a different ordering, those conventions take precedence unless they conflict with the repository’s formatting or build requirements.

Forward Declarations

Forward declarations SHOULD be used when they meaningfully reduce compilation dependencies without compromising correctness or interface clarity.

They are generally appropriate for types referenced exclusively through pointers or references when no complete definition is required.

Prefer:

#pragma once

#include <GraphicsCore/GraphicsCoreDLL.h>

class xiiResourceManager;

class XII_GRAPHICSCORE_DLL xiiResourceLoader
{
public:
  void SetResourceManager(xiiResourceManager* pManager);

private:
  xiiResourceManager* m_pManager = nullptr;
};

A forward declaration MUST NOT replace an include when a complete type is required, such as for a by-value data member, inheritance, inline member access, or another construct requiring the full definition.

Forward declarations SHOULD NOT be introduced solely to eliminate includes when doing so obscures important interface dependencies.

Dependency Hygiene

Header dependencies influence compilation time, coupling, and the scope of rebuilds.

• Avoid including implementation-only dependencies in public headers.
• Move implementation-specific includes into .cpp files where practical.
• Do not include headers solely because they were historically present.
• Remove unused includes when modifying the surrounding code, provided doing so does not introduce unrelated changes.
• Do not introduce monolithic convenience headers into low-level modules when narrowly scoped dependencies are available.
• Changes to public headers SHOULD consider their impact on downstream compilation and module boundaries.

Guiding principle:

Every include should represent an intentional dependency. Headers must stand independently, module boundaries must remain explicit, and include ordering must follow the repository’s established conventions.

2.6 Section Separators

Section separators MAY be used to organize substantial implementation files and distinguish meaningful groups of functionality.

Their purpose is navigation and structural clarity, not decoration.

General Requirements

• Use the repository’s established separator style where section dividers are appropriate.
• Prefer section separators between logically distinct implementation groups.
• Do not insert separators between every small function or helper.
• Avoid excessive or deeply nested visual section hierarchies.
• Section organization SHOULD reflect the responsibilities of the implementation rather than arbitrary file length.
• Do not use section separators to compensate for unrelated responsibilities that should be separated into different components or translation units.

Prefer:

//////////////////////////////////////////////////////////////////////////

xiiResourceRegistry::xiiResourceRegistry() = default;

xiiResourceRegistry::~xiiResourceRegistry()
{
  Clear();
}

//////////////////////////////////////////////////////////////////////////

void xiiResourceRegistry::Clear()
{
  m_Entries.Clear();
}

Separators can improve navigation when distinguishing construction and destruction, resource management, serialization, or other substantial implementation groups.

For short implementation files containing a small number of closely related functions, additional separators are generally unnecessary.

Structural Organization

When section separators are used, related implementations SHOULD remain grouped consistently.

Examples of meaningful groups include:

• Construction, initialization, and destruction.
• Public interface implementations.
• Resource creation and release.
• State management and synchronization.
• Serialization and deserialization.
• Internal algorithms and helper functions.
• Platform-specific implementations.

Section dividers MUST NOT replace clear function names, cohesive class design, or appropriate source-file organization.

An excessively large implementation file should be evaluated for responsibility boundaries rather than divided indefinitely with decorative comments.

Guiding principle:

Use visual separators to clarify meaningful implementation boundaries, not to disguise unnecessary complexity or fragmented design.

2.7 File Endings and Comments

Source files MUST maintain consistent file structure, meaningful documentation, and a clean version-control history.

Comments should explain intent, constraints, and non-obvious decisions rather than repeat information already apparent from the code.

File Requirements

• Source files MUST end with a single newline.
• Trailing whitespace and unintended mixed line endings MUST NOT be introduced.
• Required copyright and license notices MUST follow the repository’s established form.
• Existing license notices MUST NOT be removed or modified without authorization.
• Contributors MUST NOT copy personal or third-party copyright notices into unrelated files without an applicable legal or licensing basis.
• Required static-link registration macros MUST be preserved where applicable. See §17.
• Generated source files MUST retain any required generator metadata, registration declarations, or structural markers.

Commenting Requirements

Comments SHOULD explain information that cannot be communicated adequately through names, types, interfaces, or straightforward implementation structure.

Appropriate comments include:

• Non-obvious algorithmic decisions.
• Platform-specific behavior or limitations.
• Ownership, lifetime, or synchronization constraints.
• Requirements imposed by external APIs or binary formats.
• Performance-sensitive assumptions supported by measurements.
• Intentional deviations from otherwise established conventions.
• Compatibility requirements that are not apparent from the surrounding code.

Prefer:

// Resource destruction is deferred until submitted GPU work
// no longer references the underlying allocation.
QueueResourceDestruction(hResource);

Avoid:

// Destroy the resource.
DestroyResource(hResource);

Comments that merely restate the next operation add noise without improving comprehension.

Obsolete Code and Temporary Changes

• Do not retain commented-out implementations as a substitute for version control.
• Obsolete code MUST be removed rather than indefinitely disabled.
• #if 0 blocks SHOULD NOT be used to preserve abandoned implementations.
• Temporary debugging statements, experimental code, and instrumentation MUST be removed before submission unless intentionally retained as supported functionality.
• TODO and FIXME comments SHOULD identify a concrete issue or required action rather than serve as vague placeholders.
• Workarounds SHOULD explain the underlying constraint and, where appropriate, reference the associated issue or dependency.

Avoid:

#if 0
void ProcessResources()
{
  // Previous implementation retained indefinitely.
}
#endif

Version control already preserves historical implementations. Keeping disabled code in active source files increases maintenance burden and obscures the current implementation.

Comment Accuracy

Comments are part of the maintained source contract.

• Comments MUST NOT contradict the implementation.
• When behavior changes, associated comments and documentation MUST be updated.
• Avoid speculative comments that describe intended future behavior as though it already exists.
• Do not document guarantees that the implementation does not enforce.
• Prefer removing an inaccurate comment over preserving it for historical reasons.

Guiding principle:

Source files should contain only the active implementation and the documentation necessary to understand it. Comments must preserve intent, explain constraints, and remain accurate as the code evolves.

2.8 Header and Implementation File Organization

XII follows a consistent source-file organization in which implementation files are placed within an Implementation directory alongside their corresponding public headers.

This convention separates interface declarations from implementation details while preserving the logical grouping of related functionality.

General Requirements

• Public header files (.h) MUST reside in the directory corresponding to their module and subsystem.
• C++ implementation files (.cpp) MUST reside in an Implementation subdirectory within the same directory as their corresponding headers.
• The Implementation directory MUST use the exact capitalization established by the repository.
• Related headers and implementation files SHOULD share the same base filename to make their relationship immediately apparent.
• Implementation files MUST NOT be placed directly alongside public headers unless an established repository convention or technical requirement explicitly permits it.
• Private implementation headers SHOULD reside in the Implementation directory when they are not intended for consumption outside the subsystem.
• Do not introduce unnecessary directory hierarchies or separate implementation directories when an existing subsystem structure is sufficient.

Directory Structure

Prefer:

GraphicsCore/
└── Pipeline/
    ├── RenderGraph.h
    ├── RenderGraphManager.h
    └── Implementation/
        ├── RenderGraph.cpp
        └── RenderGraphManager.cpp

Avoid:

GraphicsCore/
└── Pipeline/
    ├── RenderGraph.h
    ├── RenderGraph.cpp
    ├── RenderGraphManager.h
    └── RenderGraphManager.cpp

The preferred structure keeps public interfaces immediately discoverable while grouping their implementations in a predictable location.

Implementation-Specific Headers

Headers that define private implementation details SHOULD remain within the Implementation directory when they are not part of the module’s public interface.

Examples include internal helper classes, private data structures, and implementation-specific utilities.

Such headers MUST NOT be treated as public API merely because they are accessible through the repository’s include paths.

If a private header becomes necessary for multiple independent subsystems, its responsibility and appropriate module placement SHOULD be reconsidered rather than exposing implementation details by convenience.

Exceptions

Exceptions MAY be permitted for generated sources, platform-specific implementations, third-party code, or files subject to established build-system conventions.

Any deviation SHOULD follow an existing repository pattern and have a clear technical justification.

Guiding principle:

Keep public interfaces visible and their implementations nearby. A predictable directory structure should make code easy to locate, navigate, and maintain without exposing unnecessary implementation details.

3. Naming Conventions

Consistent naming is essential for readability, maintainability, and discoverability across XII’s modules. Identifiers should communicate their purpose, type semantics, ownership context, and relationship to the surrounding system without requiring unnecessary inspection of their declarations or implementations.

XII uses a combination of PascalCase, descriptive identifiers, and type-dependent prefixes to maintain consistency across its C++ codebase.

Preserved baseline rule: Type-dependent prefixes are mandatory for member variables only when an applicable type is known. Local variables and function parameters may use type-dependent prefixes, but their use remains at the programmer’s discretion.

Examples throughout this document generally use type-dependent prefixes for local variables and parameters to remain consistent with common XII conventions. These examples MUST NOT be interpreted as making such prefixes mandatory outside member variables.

3.1 Type and Symbol Names

Names MUST be descriptive, consistent with established engine terminology, and appropriate to the responsibility of the symbol.

General Requirements

• Public symbols MUST use terminology consistent with the subsystem that owns them.
• Names SHOULD describe responsibilities, behavior, or meaning rather than incidental implementation details.
• Avoid abbreviations that require private knowledge of the implementation.
• Prefer established engine terminology over inventing alternative names for existing concepts.
• Do not encode unnecessary implementation details into identifiers when those details may change.
• Distinguish operations with different semantics through meaningful names rather than arbitrary suffixes.
• Do not rename stable public symbols solely for stylistic consistency when doing so would create unnecessary compatibility changes.
• C++ keywords, reserved identifiers, and implementation-reserved naming patterns MUST NOT be used for user-defined symbols.

Prefer:

xiiResult InitializeResources();
xiiUInt32 GetResourceCount() const;
bool IsResourceReady(xiiResourceHandle hResource) const;

Avoid:

xiiResult InitRes();
xiiUInt32 GetRC() const;
bool Check(xiiResourceHandle hResource) const;

Names should be understandable without relying on undocumented abbreviations or examining the implementation.

3.2 Type-Dependent Member Prefixes

Type-dependent prefixes are mandatory for member variables when the member’s type belongs to a recognized category.

These prefixes communicate the semantic type of the stored value and are applied after the applicable member or static marker.

Prefix Requirements

• Member variables MUST use their applicable type-dependent prefixes.
• Prefixes MUST represent the semantic type of the value rather than a convenient or misleading interpretation.
• Type aliases and wrappers SHOULD follow the semantic category they represent when that category is unambiguous.
• Do not assign pointer prefixes to integer values merely because those values represent memory addresses.
• Handles MUST use the h prefix rather than the p prefix, even when they refer to independently allocated resources.
• Smart pointers such as xiiUniquePtr and xiiSharedPtr use the p prefix because they represent pointer-based access and ownership.
• Types without an established prefix MUST NOT be assigned arbitrary prefixes merely to maintain a visual pattern.
• Prefixes SHOULD remain consistent when a member’s type changes. A type change that alters the appropriate prefix should trigger a corresponding identifier review.

Prefer:

class xiiSimulationState
{
private:
  xiiUInt64 m_uiSimulationStep = 0U;
  xiiInt32  m_iPriority        = 0;
  bool      m_bActive          = false;
  float     m_fDeltaTime       = 0.0f;

  xiiHashedString               m_sName;
  xiiResourceHandle             m_hResource;
  xiiUniquePtr<xiiResourceData> m_pResourceData;

  xiiVec3 m_vPosition;
  xiiQuat m_qRotation;
  xiiMat4 m_mTransform;

  xiiDynamicArray<xiiUInt32> m_ActiveIndices;
};

The spelling m_mTransform is intentional:

• The first m_ identifies an instance member.
• The second m identifies a matrix.

Likewise, m_pResourceData identifies a member containing a pointer-like object, while m_hResource identifies a resource handle.

Semantic Types and Aliases

A prefix must not misrepresent the underlying abstraction.

For example:

xiiUInt64          m_uiGpuAddress = 0U;
xiiResourceHandle  m_hResource;
xiiUniquePtr<Data> m_pData;

A GPU address represented as an unsigned integer uses ui, even if the value refers to a location in GPU memory.

An opaque resource handle uses h, regardless of how the handle is implemented internally.

The naming convention must remain faithful to the type’s public semantics rather than its private representation.

3.3 Public Fields

The existing XII naming policy does not require the m_ prefix for public non-static data members.

However, many existing public engine structures use m_ consistently, particularly configuration objects, descriptors, reflected structures, and serialized data.

For new public data structures, contributors SHOULD follow the naming convention established by the surrounding module.

General Requirements

• Public fields SHOULD use a consistent naming style within the same structure.
• New configuration and descriptor structures SHOULD follow the established conventions of neighboring public data types.
• Public field names MUST communicate their intended meaning and, where relevant, units or state.
• Do not mix prefixed and unprefixed public fields arbitrarily within a new structure.
• Existing public fields MUST NOT be renamed solely for aesthetic consistency without evaluating compatibility implications.
• Changes to reflected or serialized public fields MUST consider their effect on persistent data, tools, scripts, plugins, and external consumers.

Prefer:

struct xiiSimulationSettings
{
  bool      m_bEnableSimulation = true;
  xiiUInt32 m_uiMaxIterations   = 128U;
  float     m_fFixedTimeStep    = 0.016f;
};

This structure follows a consistent field convention and communicates each value’s semantics through its name.

Public fields may be accessed directly when the structure intentionally represents data rather than an encapsulated behavioral abstraction.

Do not introduce getters and setters for every field of a simple configuration or value structure unless doing so protects meaningful invariants or provides necessary behavior.

3.4 Private, Protected, and Static Fields

Private and protected instance fields MUST use the m_ prefix followed by the appropriate type-dependent prefix, where applicable.

Private and protected mutable static fields MUST use the s_ prefix followed by the appropriate type-dependent prefix.

Compile-time constants should use descriptive PascalCase names.

Prefer:

class xiiCounter
{
public:
  XII_ALWAYS_INLINE xiiUInt32 GetCount() const
  {
    return m_uiCount;
  }

private:
  static constexpr xiiUInt32 MaxCount = 1024U;

  static xiiUInt32 s_uiLiveCounters;

  xiiUInt32 m_uiCount = 0U;
};

General Requirements

• Instance fields MUST be distinguishable from local variables and parameters through the m_ prefix.
• Private and protected mutable static fields MUST use s_.
• Private and protected static constants SHOULD use PascalCase without the mutable-static prefix.
• Prefer constexpr for compile-time constants when supported by the required semantics.
• Avoid mutable static state when ordinary object ownership or explicitly managed subsystem state provides a clearer design.
• Static data MUST have well-defined initialization, synchronization, and destruction behavior.
• Public mutable static fields SHOULD be avoided when they expose internal state or permit uncontrolled modification.

The existing naming policy exempts public static fields from the private-static naming requirement.

Nevertheless, public mutable state should not be introduced casually. Prefer named constants or controlled operations when invariants or synchronization requirements must be preserved.

3.5 Fixed-Size Arrays

The existing XII naming policy permits a relaxed member-prefix convention for fixed-size arrays.

Both of the following declarations are permitted:

bool m_bActiveFlags[3];
bool mActiveFlags[3];

For new code, the conventional typed-member form is RECOMMENDED because it remains consistent with other member declarations.

General Requirements

• Fixed-size arrays MAY use the relaxed member-prefix convention established by the original policy.
• New fixed-size array members SHOULD use the conventional m_ and applicable type prefix.
• A class or structure SHOULD use one consistent naming style for its fixed-size array members.
• Existing array members MUST NOT be renamed solely to eliminate a permitted naming exception.
• Array names SHOULD describe the meaning of their elements rather than merely identify the storage as an array.

Prefer for new code:

class xiiInputState
{
private:
  bool      m_bButtonPressed[8] = {};
  xiiUInt32 m_uiEventCounts[8]  = {};
};

A fixed-size array exception does not remove the requirement for meaningful names or consistent member organization.

3.6 Boolean and Query Names

Boolean identifiers and query methods SHOULD communicate conditions that can be read naturally in control-flow expressions.

A boolean name should make its true and false meanings immediately apparent.

General Requirements

• Boolean member fields MUST use the b type prefix where applicable.
• Prefer affirmative condition names over unnecessary negations.
• Avoid ambiguous terms such as Flag, Status, State, or Check when a more specific condition can be expressed.
• Boolean query methods SHOULD use Is, Has, or Can according to their semantics.
• Queries SHOULD NOT modify observable object state unless their contract explicitly communicates that behavior.
• Do not use Get for boolean queries when Is, Has, or Can communicates the intended meaning more precisely.

Prefer:

if (m_bSimulationActive && pWorld != nullptr)
{
  AdvanceSimulation();
}

Avoid:

if (!m_bSimulationDisabled && pWorld != nullptr)
{
  AdvanceSimulation();
}

Prefer query names that communicate distinct meanings:

These conventions are semantic guidelines rather than a requirement to mechanically rename established public APIs.

Guiding principle:

A boolean name should describe what is true, and a query method should communicate what it evaluates.

3.7 Names Must Distinguish Identity, Units, and Scope

Names MUST distinguish concepts that share similar underlying representations but have different meanings.

This is especially important in systems involving resource handles, identifiers, time measurements, memory offsets, simulation state, and asynchronous execution.

General Requirements

• Use distinct names for logically different identifiers, even when their underlying types are identical.
• Include units in identifiers when values could otherwise be misinterpreted.
• Distinguish indices, counts, offsets, capacities, and sizes according to their actual semantics.
• Distinguish CPU submission, GPU completion, and application-level frame progression when those concepts are independently tracked.
• Avoid generic names when the surrounding scope does not make their meaning unambiguous.
• Prefer domain-specific terminology over implementation-dependent descriptions.
• Names MUST NOT suggest guarantees that the underlying value or operation does not provide.

Prefer:

xiiResourceHandle hResource;
xiiUInt64         uiSimulationStep;
xiiUInt64         uiCompletedStep;
xiiUInt32         uiBufferSizeBytes;
xiiUInt32         uiElementCount;
xiiUInt32         uiElementOffset;
float             fElapsedTimeSeconds;

Avoid:

xiiResourceHandle hObject;
xiiUInt64         uiIndex;
xiiUInt64         uiDone;
xiiUInt32         uiSize;
xiiUInt32         uiCount;
xiiUInt32         uiOffset;
float             fTime;

The shorter names may be acceptable within a tightly constrained local scope where their meaning is unambiguous. However, public interfaces and long-lived member fields should use sufficiently descriptive names to remain understandable independently of nearby implementation details.

Units and Measurements

Unit-bearing identifiers SHOULD use explicit unit suffixes when the unit is not already guaranteed by a strongly typed abstraction.

Examples include:

• uiBufferSizeBytes
• uiTimeoutMilliseconds
• fElapsedTimeSeconds
• fDistanceMeters
• uiFrequencyHertz

Do not mix values expressed in different units without explicit conversion.

Where a dedicated type already encodes units, repeating the unit in every identifier may be unnecessary.

Identity and Ordering

Identifiers should distinguish identity from position or ordering.

For example:

xiiUInt32 uiResourceIndex;
xiiUInt32 uiExecutionOrder;
xiiUInt32 uiPriority;

These names describe different concepts:

• An index identifies a position in a collection.
• An execution order describes sequencing.
• A priority expresses precedence according to a defined scheduling policy.

Do not call an execution index a priority unless the system actually implements priority semantics.

Guiding principle:

Names should communicate what a value represents, not merely how it is stored. Identity, units, ordering, and scope must remain distinguishable.

3.8 Abbreviations, Acronyms, and Spelling

Abbreviations and acronyms MUST remain consistent with established XII terminology and commonly understood technical conventions.

Names should favor clarity over brevity, particularly in public APIs and cross-module interfaces.

General Requirements

• Prefer descriptive identifiers over abbreviations that require implementation-specific knowledge.
• Preserve established engine terminology and widely recognized technical acronyms.
• Do not invent multiple abbreviations for the same concept within a subsystem.
• Avoid introducing synonyms for established terms unless they represent meaningfully different concepts.
• Public APIs SHOULD use sufficiently descriptive names to remain understandable without implementation context.
• Identifiers, comments, documentation, assertions, and diagnostic messages MUST use correct spelling and terminology.
• Acronym capitalization SHOULD follow the existing conventions of the surrounding API.
• Do not rename stable public symbols solely to expand an established abbreviation without considering compatibility consequences.

Prefer:

xiiUInt64 GetCompletedFrameIndex() const;
xiiUInt32 GetActiveResourceCount() const;
bool IsResourceResident() const;

Avoid:

xiiUInt64 GetCFI() const;
xiiUInt32 GetARC() const;
bool IsResRes() const;

Established Acronyms

Common technical abbreviations are acceptable when they are widely recognized or already established within XII.

Examples include:

An acronym SHOULD NOT be used when its meaning is ambiguous within the relevant subsystem.

For example, RT may refer to a render target or ray tracing. Where both concepts appear in the same context, prefer a more explicit name.

Terminology Consistency

A subsystem SHOULD establish consistent terminology for its primary concepts.

For example, if an API uses the term ResourceHandle, related interfaces should not arbitrarily alternate between ResourceId, ResourceReference, and ResourceToken unless those names represent distinct abstractions.

Likewise, distinguish registration, creation, acquisition, initialization, and loading when their operations have different lifecycle semantics.

Spelling and terminology are particularly important for public interfaces because names become part of the contract that developers rely on.

Guiding principle:

Names are part of the interface. Favor clarity, preserve established terminology, and use abbreviations only when their meaning is sufficiently well understood.

4. File Organization and Headers

Source files and public interfaces MUST be organized to preserve clear module boundaries, minimize compilation dependencies, and support independent development across XII’s subsystems.

This section extends the source layout requirements established in §2, focusing on header design, dependency management, translation-unit boundaries, template organization, and binary interfaces.

Formatting, include ordering, license placement, and the Implementation directory convention are governed by §§2.1–2.8 and are not repeated here.

4.1 One Clear Primary Responsibility per File

Each source file SHOULD have a coherent primary responsibility corresponding to a class, subsystem operation, or closely related group of functions.

• Prefer organizing files around meaningful responsibilities rather than arbitrary implementation size.
• Keep implementation-specific helpers near the component that owns them.
• Do not move unrelated types into generic Utilities, Common, or Helpers files merely because their implementations are small.
• Extract reusable functionality into independent files only when it has a clear responsibility and demonstrated consumers.
• Avoid distributing a single cohesive implementation across multiple translation units without a meaningful architectural reason.
• Avoid accumulating unrelated functionality in an existing file solely because it is convenient.
• File names SHOULD identify their principal type, interface, or responsibility.

Public headers and corresponding implementation files follow the directory organization defined in §2.8.

Core/
└── ResourceManager/
    ├── ResourceManager.h
    ├── ResourceManagerTypes.h
    └── Implementation/
        ├── ResourceManager.cpp
        └── ResourceManagerTypes.cpp

Related types may share a file when their responsibilities are inseparable and separating them would introduce unnecessary dependencies or fragmentation.

Guiding principle:

Organize files around cohesive responsibilities, not arbitrary size limits or superficial classification.

4.2 Header Self-Sufficiency and Complete Types

Public headers MUST be independently compilable and must declare their dependencies explicitly.

A header must not rely on another header, a precompiled header, or a particular inclusion order to provide required declarations.

The include organization and module DLL.h placement requirements are defined in §2.5.

General Requirements

• Public headers MUST contain the declarations and dependencies necessary for their independent compilation.
• A header MUST NOT rely on transitive includes for symbols it directly requires.
• Complete type definitions MUST be available wherever the C++ language requires them.
• Forward declarations SHOULD be used where legal and beneficial to reduce unnecessary dependencies.
• Avoid including implementation-specific headers in public interfaces unless their definitions are genuinely required.
• Public headers SHOULD minimize dependencies on unrelated modules.
• Header self-sufficiency SHOULD be validated through independent compilation or automated header checks.

Prefer:

// ResourceLoader.h

#pragma once

#include <Core/CoreDLL.h>

#include <Foundation/Strings/StringView.h>
#include <Foundation/Types/Result.h>

class xiiResourceManager;

class XII_CORE_DLL xiiResourceLoader
{
public:
  xiiResult LoadResource(xiiStringView sPath);

  void SetResourceManager(xiiResourceManager* pManager);

private:
  xiiResourceManager* m_pManager = nullptr;
};

The forward declaration is sufficient because the header only stores a non-owning pointer to xiiResourceManager.

The corresponding implementation file includes the complete definition when it accesses the manager’s members.

Incomplete Types and Ownership

Forward declarations are not universally interchangeable with includes.

Complete types are generally required for:

• Non-static data members stored by value.
• Base classes.
• Inline functions that access type members.
• Operations requiring an object’s size or alignment.
• Template instantiations whose definitions require complete types.
• Destruction or allocation operations requiring a complete type.

Smart pointers may support declarations involving incomplete types, but their destruction and instantiation requirements must be respected.

Prefer:

// SimulationController.h

#pragma once

#include <Core/CoreDLL.h>

#include <Foundation/Types/UniquePtr.h>

class xiiSimulationData;

class XII_CORE_DLL xiiSimulationController
{
public:
  xiiSimulationController();
  ~xiiSimulationController();

private:
  xiiUniquePtr<xiiSimulationData> m_pData;
};

// Implementation/SimulationController.cpp

#include <Core/CorePCH.h>

#include <Core/Simulation/SimulationController.h>
#include <Core/Simulation/SimulationData.h>

xiiSimulationController::xiiSimulationController() = default;

xiiSimulationController::~xiiSimulationController() = default;

This pattern is valid when the smart pointer’s implementation supports incomplete types and the out-of-line destructor is instantiated with the complete definition available.

Do not assume that all ownership wrappers have identical incomplete-type requirements.

Guiding principle:

Headers must provide every dependency required by their contracts while avoiding dependencies needed only by their implementations.

4.3 Header Inclusion and One Definition Rule

XII uses #pragma once as its established header inclusion mechanism, as specified in §2.5.

In addition to preventing repeated inclusion, header design MUST respect C++ linkage and the One Definition Rule (ODR).

General Requirements

• Header definitions MUST be safe for inclusion in multiple translation units.
• Ordinary non-inline functions and variables with external linkage MUST NOT be defined in headers unless the language explicitly permits the intended definition pattern.
• Use inline or inline constexpr where appropriate for definitions intentionally shared across translation units.
• Avoid namespace-scope mutable state defined in headers.
• Do not rely on #pragma once to prevent ODR violations across separate translation units.
• Header-defined templates, inline functions, and constants MUST have consistent definitions across all translation units.
• Conditional compilation MUST NOT produce incompatible definitions of the same externally linked type or symbol.

Avoid:

#pragma once

xiiUInt32 GetDefaultCapacity()
{
  return 1024U;
}

Including this header in multiple translation units can produce multiple definitions of the same externally linked function.

Prefer:

#pragma once

XII_ALWAYS_INLINE xiiUInt32 GetDefaultCapacity()
{
  return 1024U;
}

Alternatively, declare the function in the header and provide its definition in the corresponding .cpp file.

For non-trivial functions, the latter is generally preferred.

Guiding principle:

Header inclusion protection prevents repeated inclusion within a translation unit; correct linkage and definition placement prevent conflicts across translation units.

4.4 Public Interface Exposure and Dependency Boundaries

Public headers form part of a module’s contract and influence every consumer that includes them.

Changes to public headers must therefore consider dependency direction, compilation costs, portability, and interface stability.

General Requirements

• Public interfaces MUST NOT expose private implementation details without a documented architectural reason.
• Backend-specific declarations SHOULD remain within their corresponding backend modules.
• Platform SDK and third-party types SHOULD NOT appear in portable public interfaces unless native interoperability is an explicit responsibility.
• Implementation-only dependencies MUST remain outside public headers where practical.
• Avoid exposing concrete storage containers when the contract requires only controlled operations or abstract resource access.
• Do not include large subsystem headers solely to obtain a small declaration when a narrower dependency is available.
• Public headers MUST respect the module dependency architecture.
• Cyclic dependencies MUST be resolved through appropriate interface design rather than dependence on include order.

Resolving Cyclic Dependencies

Circular dependencies frequently indicate unclear ownership or excessively coupled interfaces.

When resolving them, consider:

1. Replacing unnecessary includes with forward declarations.
2. Moving implementation-specific dependencies into .cpp files.
3. Extracting genuinely shared types into an appropriate lower-level header.
4. Separating unrelated responsibilities into distinct components.
5. Revising ownership or interface contracts when two components depend on each other’s implementation details.

Do not introduce generic interface layers solely to eliminate every cycle without evaluating whether the additional abstraction improves the architecture.

Public Versus Private Dependencies

A dependency belongs in a public header when it is necessary to express or compile that header’s public contract.

Dependencies required only for internal algorithms, storage management, platform operations, or implementation-specific functionality should remain private.

This separation helps reduce rebuild propagation and permits implementations to evolve without unnecessarily affecting consumers.

Guiding principle:

A public header should reveal what a component provides, not how the component happens to implement it.

4.5 Internal Linkage and Translation-Unit Helpers

Symbols used exclusively within a single implementation file SHOULD have internal linkage or otherwise remain inaccessible outside that translation unit.

This prevents accidental dependencies on implementation details and reduces the risk of symbol collisions.

General Requirements

• Prefer unnamed namespaces for non-member helper functions, constants, and implementation-specific types that are local to a translation unit.
• File-local static functions and variables MAY be used when consistent with neighboring implementations.
• Do not export helper symbols without a demonstrated external consumer.
• Do not place translation-unit implementation details in public namespaces unnecessarily.
• Helpers SHOULD be located near the operations that use them when doing so improves readability.
• Avoid introducing globally accessible utility functions for logic used by only one component.
• Helper names MUST remain descriptive even when their scope is limited.

Prefer:

namespace
{
  bool IsValidCapacity(xiiUInt32 uiCapacity)
  {
    return uiCapacity > 0U;
  }

  constexpr xiiUInt32 DefaultCapacity = 1024U;
}

An unnamed namespace limits these declarations to the translation unit.

For class-specific helpers that require private member access or participate in class invariants, prefer private member functions when that more accurately expresses their responsibility.

Avoid Unnecessary External Linkage

Avoid:

bool ValidateInternalResourceState(const xiiResourceState& state)
{
  return state.m_bInitialized;
}

If this function is used only in one translation unit, external linkage provides no benefit.

Prefer giving it internal linkage unless it intentionally forms part of a shared interface.

Guiding principle:

Keep implementation details local to the smallest scope that requires them. External visibility should be intentional.

4.6 Templates, Inline Functions, and Implementation Files

Templates and inline functions require particular attention because their definitions may need to be visible to multiple translation units.

Their placement MUST satisfy C++ instantiation and linkage requirements without unnecessarily increasing compilation dependencies.

Template Requirements

• Template definitions MUST be visible at their required instantiation points unless explicit instantiation is used.
• Template implementations SHOULD follow the existing module conventions for headers and _inl.h files.
• Do not place template definitions exclusively in .cpp files unless all required specializations are explicitly instantiated and the supported instantiation contract is documented.
• Avoid unnecessarily large template implementations in public headers when the code can be organized into a dedicated implementation include.
• Template interfaces SHOULD expose only the constraints and operations required by their consumers.
• Do not introduce template abstractions solely to avoid a small amount of ordinary implementation duplication.

Inline Functions

• Small accessors and simple operations MAY be defined inline when consistent with surrounding code.
• Substantial non-template implementations SHOULD remain in .cpp files.
• Do not assume that the inline keyword guarantees machine-code inlining.
• Do not move implementations into headers solely in pursuit of speculative performance improvements.
• Header-defined functions MUST respect linkage and ODR requirements.
• Performance-motivated inlining decisions SHOULD follow the evidence-based optimization requirements in §1.5.

Prefer:

class xiiSimulationClock
{
public:
  XII_ALWAYS_INLINE xiiUInt64 GetStepCount() const
  {
    return m_uiStepCount;
  }

  void Advance(xiiTime deltaTime);

private:
  xiiUInt64 m_uiStepCount = 0U;
};

The trivial accessor is suitable for a header definition, while Advance() may contain substantial logic and belongs in the corresponding implementation file.

Template Implementation Includes

Where the repository uses _inl.h files, these SHOULD remain associated with the corresponding template declarations and follow the established include structure.

Do not introduce additional source-file extensions or template organization patterns without a clear benefit.

Guiding principle:

Place definitions where C++ requires them, but keep implementation complexity out of public headers whenever practical.

4.7 Export Boundaries and Binary Interfaces

Modules intended for dynamic linking MUST use the appropriate XII DLL export and import declarations.

Public symbol visibility is part of the module boundary and must be managed deliberately.

The placement of each module’s DLL.h is defined in §2.5.

General Requirements

• Exported classes, functions, and variables MUST use the appropriate module export macro.
• Symbols MUST NOT be exported solely for convenience when they are internal implementation details.
• Avoid unnecessary exposure of internal types, storage layouts, or ownership mechanisms through exported interfaces.
• Cross-module ownership and destruction responsibilities MUST be explicit.
• Public binary interfaces MUST consider calling conventions, type layout, alignment, and supported compiler or platform requirements.
• Changes to exported interfaces MUST be reviewed for compatibility with their intended consumers.
• Plugin and dynamically loaded module boundaries MUST account for initialization, shutdown, object lifetime, and module unloading.
• Do not assume that successful compilation guarantees binary compatibility.

Example:

class XII_GRAPHICSCORE_DLL xiiRenderGraphManager
{
public:
  xiiResult Initialize();
  void Shutdown();
};

A public class may require the module export macro when its methods or type are intended to be consumed across dynamic library boundaries.

A forward declaration alone does not necessarily require an export annotation unless its particular usage or compiler contract requires one.

ABI Considerations

Exporting a concrete C++ class may expose aspects of its binary representation to dependent modules.

Potential compatibility concerns include:

• Data member layout and alignment.
• Virtual function table organization.
• Inheritance structure.
• Constructor and destructor behavior.
• Compiler and standard-library compatibility.
• Template and container implementation details.
• Allocation and deallocation across module boundaries.
• Exception and runtime-library configuration.

Where independently versioned binary compatibility is a requirement, opaque handles, controlled interfaces, or ABI-stable façade patterns SHOULD be considered.

These mechanisms MUST NOT be introduced automatically for every internal engine interface. Their complexity should be justified by actual deployment and compatibility requirements.

Exported Ownership Contracts

When resources are created in one module and released in another, their ownership and destruction mechanism must be explicit.

Avoid interfaces that permit callers to release module-owned allocations through an incompatible allocator or runtime.

Where appropriate, provide destruction operations through the same subsystem responsible for creation.

Guiding principle:

Export only intentional contracts. Symbol visibility, ownership, and binary compatibility are architectural decisions, not merely compiler annotations.

4.8 Precompiled Headers and Compilation Independence

Precompiled headers are a build optimization and MUST NOT be treated as implicit dependency declarations.

The implementation-file ordering requirements, including placement of the repository’s license notice before the module PCH, are defined in §2.5.

General Requirements

• Implementation files belonging to PCH-enabled modules MUST use the corresponding module PCH according to the repository’s build configuration.
• Public headers MUST NOT depend on a PCH for required declarations.
• Implementation files MUST include their associated public declaration and other directly required headers.
• Removing or disabling PCH support SHOULD NOT reveal missing dependencies in otherwise valid source files.
• A PCH MUST NOT be used to conceal circular dependencies or invalid include relationships.
• Avoid adding narrowly used dependencies to a module PCH solely to eliminate local include directives.
• Changes to shared PCH content SHOULD consider compilation impact across the entire module.

Prefer:

// Copyright and license notice.

#include <Core/CorePCH.h>

#include <Foundation/Containers/DynamicArray.h>

#include <Core/Simulation/SimulationController.h>
#include <Core/Simulation/SimulationData.h>

The PCH accelerates compilation, while the remaining includes document the translation unit’s actual dependencies.

Compilation Validation

When modifying shared headers, PCH configuration, or module dependencies, contributors SHOULD consider validating builds with PCH disabled where the build system supports that configuration.

This helps identify accidental dependencies that ordinary PCH-enabled builds might conceal.

Guiding principle:

A precompiled header may accelerate compilation, but it must never determine whether otherwise valid source code can compile correctly.

4.9 Public Header Stability and Compilation Cost

Public headers are frequently included throughout the engine and can have a disproportionate effect on build times and dependency propagation.

Changes to widely included headers SHOULD consider both architectural impact and compilation cost.

General Requirements

• Keep widely consumed headers focused on the declarations required by their consumers.
• Avoid introducing heavyweight dependencies into foundational headers without a demonstrated need.
• Prefer implementation-side changes when a public contract does not need to change.
• Do not introduce large implementation bodies into public headers solely to reduce the number of source files.
• Avoid unnecessary macro definitions in shared headers.
• Shared macros MUST use appropriate naming and scope conventions to minimize collisions.
• Changes to common type definitions SHOULD consider their effects on downstream compilation, reflection, serialization, and binary compatibility.
• Build-time improvements SHOULD be measured rather than assumed.

Forward declarations, explicit dependencies, and implementation separation can reduce compilation costs, but they should not compromise interface clarity or correctness.

Guiding principle:

Shared headers are high-impact dependencies. Keep their contracts focused, their dependencies intentional, and their implementations appropriately isolated.

5. Types, Classes, and Interfaces

Types and interfaces MUST communicate their intended responsibilities, ownership semantics, invariants, and permitted operations.

XII favors cohesive types, explicit contracts, predictable object lifetimes, and controlled state transitions. Object-oriented abstractions should serve concrete architectural purposes rather than introduce unnecessary indirection or complexity.

The ownership and lifetime requirements established in §1.2, interface design principles in §1.3, and naming conventions in §3 apply throughout this section.

5.1 struct Versus class

Use struct for transparent data types whose members intentionally form a public data contract. Use class for types that encapsulate behavior, enforce invariants, manage resources, or control access to internal state.

This distinction communicates design intent. In C++, struct and class have equivalent capabilities and object representation rules; their primary language-level differences are default member accessibility and default inheritance accessibility.

General Requirements

• Use struct for plain data records, descriptors, configuration objects, and related value types whose members are intentionally accessible.
• Use class when internal state requires controlled mutation or when the type establishes meaningful behavioral invariants.
• Do not introduce getters and setters for every field of a transparent data structure without a concrete reason.
• Do not expose mutable fields merely to avoid implementing operations that preserve invariants.
• A struct MAY contain constructors, helper functions, and validation methods when these complement its role as a transparent data type.
• A class MAY contain public data when required by an established contract, but such exposure SHOULD be intentional.
• Do not select struct or class based on assumptions about performance, allocation, or memory layout.
• If a data structure develops invariants that cannot be reliably maintained through public mutation, reconsider its representation and interface.

Prefer:

struct xiiSimulationSettings
{
  xiiUInt32 m_uiMaxIterations = 128U;
  float     m_fFixedTimeStep  = 0.016f;
  bool      m_bEnableGravity  = true;
};

class xiiSimulationController
{
public:
  xiiResult Initialize(const xiiSimulationSettings& settings);
  void Shutdown();

  bool IsInitialized() const;

private:
  bool m_bInitialized = false;
};

The settings structure represents a transparent configuration contract, while the controller encapsulates lifecycle behavior and the state transitions required to maintain it.

Guiding principle:

Use struct to represent data and class to protect behavior and invariants. Choose based on semantics, not perceived complexity or performance.

5.2 Valid Initial States and Object Invariants

Objects MUST enter a well-defined state when constructed. Their initial state should be valid for the operations permitted by their documented contract.

A valid initial state does not necessarily mean a fully initialized or operational state. Some engine components require an explicit initialization phase, but their behavior before initialization must remain well-defined.

General Requirements

• Members SHOULD receive meaningful default values through default member initializers or constructors.
• Do not assume that callers will initialize every field of a public configuration structure manually.
• Members MUST NOT be read before they have been initialized.
• Default construction MUST establish a documented state.
• Partially initialized objects MUST NOT expose operations that require completed initialization without appropriate precondition enforcement.
• Sentinel values MUST have defined meanings and must not be confused with ordinary valid values.
• Prefer explicit state representations when several distinct lifecycle states must be represented.
• Avoid introducing additional state variables when the state can be derived reliably and efficiently from existing information.
• Initialization failures MUST leave objects in a documented state that permits safe cleanup, recovery, or destruction.

Prefer:

struct xiiTaskSchedulerSettings
{
  xiiUInt32 m_uiWorkerCount   = 1U;
  xiiUInt32 m_uiQueueCapacity = 1024U;
  bool      m_bEnableTracing  = false;
};

Avoid:

struct xiiTaskSchedulerSettings
{
  xiiUInt32 m_uiWorkerCount;
  xiiUInt32 m_uiQueueCapacity;
  bool      m_bEnableTracing;
};

The avoided implementation permits uninitialized members when a settings object is default-initialized without value initialization.

Initialization Failure

When construction cannot reasonably report an expected runtime failure, prefer a separate initialization operation or a factory that exposes the failure explicitly.

Prefer:

class xiiDataStore
{
public:
  xiiResult Open(xiiStringView sPath);
  void Close();

  bool IsOpen() const;

private:
  bool m_bOpen = false;
};

The Open() operation may fail because of external conditions, such as an inaccessible file or invalid data.

Such failures should be represented through xiiResult or an appropriate richer error mechanism, consistent with §1.1.

An object that requires explicit initialization MUST prevent invalid operations before initialization and maintain safe destruction semantics.

Guiding principle:

Every object must have a valid, predictable state throughout its lifetime, including before initialization, after failure, and during destruction.

5.3 Constructors and Initialization

Constructors MUST establish the invariants required for safe object use and destruction.

Prefer straightforward initialization over constructors that perform substantial work, introduce hidden dependencies, or obscure failure behavior.

General Requirements

• Prefer default member initializers for stable, context-independent defaults.
• Use constructor member initializer lists for values supplied through constructor parameters.
• References and const members MUST be initialized during construction.
• Members SHOULD be initialized in their declaration order to avoid misleading initialization dependencies.
• Constructors accepting a single argument SHOULD be marked explicit unless implicit conversion is intentional and documented.
• Prefer = default for constructors that require no custom behavior.
• Use = delete to explicitly prohibit construction or conversion operations where appropriate.
• Do not call virtual functions from constructors or destructors expecting derived-class dispatch.
• Constructors MUST NOT publish an object for external use before its required invariants are established.
• Avoid performing recoverable operations in constructors when those operations may legitimately fail and require error reporting.
• Constructor behavior SHOULD remain predictable and avoid unnecessary global state changes.

Prefer:

class xiiFrameRing
{
public:
  explicit xiiFrameRing(xiiUInt32 uiCapacity)
    : m_uiCapacity(uiCapacity)
  {
    XII_ASSERT_DEV(uiCapacity > 0U, "Frame ring capacity must be greater than zero.");
  }

private:
  xiiUInt32 m_uiCapacity;
};

Here, a positive capacity is an explicit construction precondition. The assertion detects a programmer contract violation; it does not replace validation of untrusted input at the boundary where that input enters the system.

Initialization Order

C++ initializes members in declaration order, regardless of the order in which they appear in the constructor initializer list.

Prefer:

class xiiBufferRange
{
public:
  xiiBufferRange(xiiUInt32 uiOffset, xiiUInt32 uiCount) :
    m_uiOffset(uiOffset), m_uiCount(uiCount)
  {
  }

private:
  xiiUInt32 m_uiOffset;
  xiiUInt32 m_uiCount;
};

Initializer lists SHOULD follow declaration order to make actual initialization behavior apparent.

Recoverable Construction Failures

XII does not use exceptions for ordinary error handling.

Constructors should therefore avoid operations that require recoverable failure reporting when a separate initialization method or factory provides a clearer contract.

Prefer:

class xiiResourceDatabase
{
public:
  xiiResourceDatabase() = default;

  xiiResult Initialize(xiiStringView sDatabasePath);
  void Shutdown();
};

A factory may also be appropriate when partially initialized objects must never be exposed to callers.

The choice between explicit initialization and factory construction should reflect actual ownership and lifecycle requirements, not an arbitrary preference for one pattern.

Guiding principle:

Constructors establish invariants. Recoverable initialization failures belong in operations that can communicate them explicitly.

5.4 Destructors and RAII

Resource Acquisition Is Initialization (RAII) SHOULD be used whenever resource ownership can be represented through object lifetime.

Resources acquired by an object should be released deterministically when that ownership ends.

General Requirements

• Destructors MUST preserve safe cleanup semantics.
• Destructors MUST NOT propagate exceptions across engine boundaries.
• Destruction SHOULD be deterministic and avoid unnecessary hidden work.
• Resources MUST be released using the mechanism appropriate to their ownership contract.
• RAII guards SHOULD represent one clear responsibility, such as locking a mutex, managing temporary state, or owning a resource.
• Explicit cleanup operations MUST account for subsequent destruction.
• Destructors SHOULD NOT perform unbounded waiting or unexpected expensive operations unless the type’s contract explicitly requires them.
• Resource cleanup MUST respect outstanding asynchronous operations and external lifetime dependencies.
• Destructors MUST NOT depend on virtual dispatch to derived-class implementations.

Explicit Cleanup and Destruction

When a type provides both an explicit cleanup operation and destructor-based cleanup, repeated cleanup must not violate invariants.

Prefer:

class xiiScopedOperation
{
public:
  ~xiiScopedOperation()
  {
    End();
  }

  void End()
  {
    if (!m_bActive)
      return;

    ReleaseResources();
    m_bActive = false;
  }

private:
  void ReleaseResources();

  bool m_bActive = true;
};

The End() operation is idempotent: invoking it more than once does not repeat resource release.

This is particularly useful for scoped operations that may finish explicitly before their owning object is destroyed.

However, idempotent cleanup should not be introduced universally. If repeated cleanup represents a programming error, an assertion or explicit lifecycle contract may be more appropriate.

Asynchronous Resource Destruction

Logical ownership and physical destruction may occur at different times.

For example, a GPU resource may become unavailable to new callers while its underlying allocation remains alive until submitted GPU work has completed.

Likewise, an asynchronous task may require captured state to remain valid until execution finishes.

Destructors and cleanup operations MUST respect these dependencies.

Guiding principle:

Resource ownership should determine cleanup responsibility, while the resource’s actual lifetime must satisfy every outstanding dependency.

5.5 Copy and Move Semantics

Copy and move operations MUST reflect the semantic identity, ownership, and lifetime requirements of a type.

Do not make types copyable or movable merely because C++ permits the operations.

Value Types

Value-like types SHOULD support copying when duplication is meaningful and reasonably efficient.

Examples include mathematical vectors, simple descriptors, configuration records, and small independent data objects.

Copying such objects should produce independent values with equivalent observable state.

Unique Ownership

Types that own resources exclusively MUST NOT permit copying unless a meaningful deep-copy operation is intentionally provided.

Moving may be appropriate when ownership can be transferred without violating invariants.

A move operation MUST leave both the destination and moved-from object in documented, safely destructible states.

Identity-Bearing Types

Managers, synchronization objects, resource registries, device contexts, and other identity-bearing types are generally noncopyable.

Moving such objects may also be unsafe when other components retain pointers, references, registrations, callbacks, or addresses referring to the original object.

Prefer:

class xiiTaskScheduler
{
  XII_DISALLOW_COPY_AND_ASSIGN(xiiTaskScheduler);

public:
  xiiTaskScheduler() = default;
  ~xiiTaskScheduler();

  xiiTaskScheduler(xiiTaskScheduler&&) = delete;
  xiiTaskScheduler& operator=(xiiTaskScheduler&&) = delete;
};

The move operations are explicitly prohibited because moving a scheduler may invalidate synchronization or registration state associated with its identity.

General Requirements

• Copy and move operations MUST preserve documented invariants.
• Exclusive ownership MUST NOT be duplicated accidentally.
• Moving a type MUST NOT invalidate externally registered addresses or references unless the contract explicitly permits it.
• Prefer compiler-generated copy and move operations when their behavior matches the intended semantics.
• Custom special member functions SHOULD be introduced only when ownership, resource management, or invariants require them.
• When declaring custom destructors or copy operations, review whether move operations must be explicitly defined or deleted.
• Do not infer a type’s move behavior solely from the name of an engine macro.
• The actual definitions of copy-disabling macros MUST be considered before relying on their effects.

Prefer the Rule of Zero for types whose members already manage their own resources correctly.

For ownership-bearing types that require custom special member functions, define or prohibit the relevant operations deliberately.

Guiding principle:

Copying duplicates a value; moving transfers state or ownership. Both operations must be valid according to the type’s semantics, not merely its syntax.

5.6 Inheritance and Virtual Dispatch

Inheritance SHOULD represent a genuine substitutability relationship, an established extension contract, or a deliberate form of interface polymorphism.

Prefer composition when the objective is merely to reuse implementation details.

General Requirements

• Public inheritance MUST preserve the behavioral contract of the base type.
• Derived implementations MUST NOT weaken required preconditions or violate established postconditions.
• Overridden virtual functions MUST use override.
• Use final only when preventing further inheritance or overriding is an intentional design requirement.
• Polymorphic base classes MUST have an appropriate virtual destructor when deletion through a base pointer is permitted.
• Do not introduce virtual methods solely to make a type hypothetically extensible.
• Avoid deep inheritance hierarchies that obscure ownership, initialization, or behavioral responsibilities.
• Do not use inheritance merely to share member variables or common helper implementations.
• Virtual dispatch overhead SHOULD be evaluated through profiling when it occurs in demonstrated hot paths, as described in §1.5.

Prefer:

class xiiSimulationBackend
{
public:
  virtual ~xiiSimulationBackend() = default;

  virtual xiiResult Initialize() = 0;
  virtual void Shutdown() = 0;
  virtual void StepSimulation(float fDeltaTime) = 0;
};

class xiiCpuSimulationBackend final : public xiiSimulationBackend
{
public:
  xiiResult Initialize() override;
  void Shutdown() override;
  void StepSimulation(float fDeltaTime) override;
};

The derived type implements an established behavioral interface rather than inheriting solely to reuse implementation.

Virtual Destruction

A base class intended for polymorphic deletion MUST provide a public virtual destructor or another explicitly enforced destruction mechanism.

A protected non-virtual destructor may be appropriate for interfaces that prohibit deletion through the base type and delegate destruction to a controlled owner.

Do not add virtual destructors to every class automatically. Polymorphism and destruction semantics must justify their use.

Avoiding Artificial Polymorphism

Do not introduce base classes, virtual functions, or runtime type registries when the set of implementations is fixed and ordinary composition or direct calls provide a simpler design.

Conversely, do not replace a cohesive polymorphic interface with manual type identifiers and conditional dispatch without a demonstrated benefit.

Guiding principle:

Inheritance defines behavioral relationships. Use it to express substitutability, not merely to share code or anticipate hypothetical extensions.

5.7 Interface Granularity and Capability Exposure

Interfaces MUST expose meaningful capabilities while minimizing unnecessary knowledge of internal state.

The general principles of small, cohesive interfaces are established in §1.3. This section focuses on their application to C++ type design.

General Requirements

• Public methods SHOULD represent meaningful operations rather than direct access to implementation details.
• Avoid exposing internal containers, registration tables, synchronization objects, or mutable storage without a documented requirement.
• Do not return unrestricted mutable references to manager-owned resources when doing so bypasses invariants.
• Prefer controlled operations when resource mutation requires validation, synchronization, or lifecycle management.
• Do not introduce multiple layers of accessors that merely forward calls without establishing meaningful contracts.
• Avoid expanding interfaces to support hypothetical consumers.
• Interface methods SHOULD have clearly defined preconditions, postconditions, and failure behavior.
• Read-only access SHOULD be preferred when mutation is unnecessary.
• Borrowed access MUST have valid and understandable lifetime guarantees.

Prefer:

class xiiTaskRegistry
{
public:
  xiiResult RegisterTask(xiiTaskHandle hTask);
  xiiResult UnregisterTask(xiiTaskHandle hTask);

  bool IsRegistered(xiiTaskHandle hTask) const;
};

Avoid:

class xiiTaskRegistry
{
public:
  xiiDynamicArray<TaskEntry>& GetMutableEntries();
};

The avoided interface exposes internal storage and permits callers to bypass registration rules, potentially invalidating indices, handles, or synchronization assumptions.

Capability-Oriented Interfaces

Interfaces should communicate what consumers are permitted to do, not merely what data the implementation contains.

However, exposing an immutable view or container may be appropriate when iteration itself is a documented capability and its lifetime and invalidation semantics are well-defined.

Controlled interfaces should not become unnecessarily elaborate wrappers around operations that are already safe and self-explanatory.

Guiding principle:

Expose the operations consumers need while retaining control of the invariants consumers must not violate.

5.8 Encapsulation and Invariant Preservation

Encapsulation is meaningful only when it protects an actual contract.

Marking a field private does not guarantee encapsulation if callers can obtain unrestricted mutable access to the same state.

General Requirements

• State transitions MUST preserve the invariants owned by the component.
• Mutable access to internal state SHOULD be restricted when arbitrary modification could violate those invariants.
• Methods SHOULD express valid transitions rather than requiring callers to coordinate internal fields manually.
• Internal synchronization requirements MUST NOT be bypassed through unguarded public references or pointers.
• Avoid exposing implementation storage solely to simplify a caller’s code.
• Do not introduce accessors that provide no meaningful encapsulation benefit.
• Invariants MUST remain valid after operations that report failure, subject to their documented failure guarantees.
• Components SHOULD centralize validation and transition logic rather than duplicate it across unrelated callers.

Prefer:

class xiiSimulationSession
{
public:
  xiiResult Begin()
  {
    if (m_bActive)
      return XII_FAILURE;

    m_bActive = true;
    return XII_SUCCESS;
  }

  void End()
  {
    m_bActive = false;
  }

  XII_ALWAYS_INLINE bool IsActive() const
  {
    return m_bActive;
  }

private:
  bool m_bActive = false;
};

Avoid:

class xiiSimulationSession
{
public:
  XII_ALWAYS_INLINE bool& GetActiveState()
  {
    return m_bActive;
  }

private:
  bool m_bActive = false;
};

The avoided implementation allows external code to modify state without passing through the operations responsible for enforcing valid transitions.

The preferred example is intentionally simple; Begin() and End() are justified when they represent meaningful lifecycle transitions. A plain boolean field in a transparent configuration structure would not require this abstraction.

Guiding principle:

Encapsulation is the enforcement of meaningful contracts, not the mechanical replacement of fields with getters and setters.

5.9 Separate Ownership from Execution Policy

Object ownership and execution policy are distinct architectural responsibilities.

A component may own, register, or manage the lifetime of an object without determining when or how that object executes.

These responsibilities SHOULD remain separate unless their coupling is an explicit part of the subsystem’s contract.

General Requirements

• Registration MUST NOT implicitly imply execution unless documented by the owning subsystem.
• Ownership MUST NOT automatically imply scheduling, activation, or per-frame participation.
• Execution order, priority, frequency, and synchronization SHOULD be represented independently when they are distinct concepts.
• Avoid embedding global scheduling assumptions into otherwise reusable resource or object managers.
• Components SHOULD be reusable across execution contexts when their responsibilities permit it.
• Do not introduce a separate scheduler or execution abstraction when ownership and execution are inherently inseparable and no meaningful benefit would result.
• Changes to execution policy SHOULD NOT require restructuring ownership contracts unnecessarily.

Example

A simulation registry may own simulation instances while a separate scheduler determines which instances participate in a particular update.

class xiiSimulationRegistry
{
public:
  xiiSimulationHandle CreateSimulation();
  xiiResult DestroySimulation(xiiSimulationHandle hSimulation);
};

class xiiSimulationScheduler
{
public:
  xiiResult ScheduleSimulation(xiiSimulationHandle hSimulation);
  xiiResult UnscheduleSimulation(xiiSimulationHandle hSimulation);

  void ExecuteScheduled(float fDeltaTime);
};

The registry owns simulation lifetime, while the scheduler controls execution participation.

This separation is appropriate when simulations may be created independently of scheduling or participate in different execution policies.

For smaller systems where ownership and execution are necessarily coupled, a single cohesive component may be preferable.

Guiding principle:

Ownership determines who manages an object. Execution policy determines when and how it participates in work. Do not conflate these responsibilities without a concrete reason.

5.10 Favor Composition Over Unnecessary Inheritance

Composition SHOULD be preferred when a type needs to use or own another component rather than satisfy its behavioral contract.

Composition permits responsibilities to evolve independently and generally makes ownership and lifetime relationships easier to understand.

General Requirements

• Prefer composition for owned utilities, allocators, profilers, caches, synchronization objects, and supporting services.
• Use inheritance when substitutability or an established extension interface provides a meaningful benefit.
• Avoid inheriting from a type solely to access its implementation details or reuse a few methods.
• Do not introduce deep inheritance hierarchies to share common data members.
• Composed objects MUST have clearly defined ownership and lifetime relationships.
• Prefer direct composition over unnecessary service locators, global registries, or dependency injection layers.
• Dependencies SHOULD be provided explicitly when doing so clarifies ownership and testability.
• Do not fragment a cohesive type into numerous single-purpose objects without a demonstrated architectural benefit.

Prefer:

class xiiSimulationSystem
{
public:
  xiiResult Initialize();
  void Shutdown();

private:
  xiiTaskScheduler   m_TaskScheduler;
  xiiSimulationClock m_SimulationClock;
};

Avoid:

class xiiSimulationSystem : public xiiTaskScheduler, public xiiSimulationClock
{
public:
  xiiResult Initialize();
  void Shutdown();
};

The simulation system uses scheduling and timing capabilities; it is not itself necessarily a scheduler or a clock.

Composition communicates that relationship without exposing the implementation details of its supporting components through inheritance.

Dependency Lifetime

Composition also clarifies destruction order.

C++ destroys member objects in the reverse order of their declaration. Dependencies between composed members MUST respect this behavior.

When one member depends on another during destruction, their declaration order and cleanup contracts must ensure that the dependency remains alive for the required duration.

Guiding principle:

Prefer composition to express what a component has or uses. Reserve inheritance for what a component genuinely is or promises to implement.

6. Initialization, Ownership, and Lifetime

Resource management in XII MUST be deterministic, explicit, and consistent with the lifetime guarantees of the underlying subsystem.

This applies to ordinary heap allocations, engine-managed resources, platform objects, asynchronous operations, GPU resources, plugin registrations, and any object whose lifetime extends beyond a single scope.

The general ownership principles established in §1.2 and the type design requirements in §5 apply throughout this section. This section defines the practical requirements for allocation, initialization, borrowing, stable identity, resource invalidation, and coordinated destruction.

6.1 The Ownership Rule

Every dynamically allocated object and long-lived resource MUST have an identifiable owner or an explicitly defined shared ownership policy.

Ownership determines which component is responsible for releasing a resource. Borrowed access does not transfer or extend that responsibility.

General Requirements

• Every resource MUST have a clearly defined ownership and destruction mechanism.
• Prefer automatic storage and value semantics when dynamic allocation or independent identity is unnecessary.
• Use xiiUniquePtr when exclusive heap ownership is appropriate.
• Use xiiSharedPtr only when multiple independent owners genuinely require shared lifetime management.
• Raw pointers, references, spans, and views MUST be treated as non-owning unless an API explicitly documents an ownership-transfer contract.
• Ownership transfers MUST be visible through the API and supported by the relevant type semantics.
• Do not introduce shared ownership merely to compensate for unclear lifetime relationships.
• Do not maintain competing ownership mechanisms for the same resource.
• Resource-owning objects MUST remain safely destructible after partial initialization or recoverable failure.
• Ownership and thread safety MUST be evaluated independently.

Prefer:

struct xiiSimulationEntry
{
  xiiUniquePtr<xiiSimulation> m_pSimulation;
  xiiSimulationState          m_State;
};

The entry has exclusive ownership of its simulation object, while the associated state follows the entry’s lifetime.

Avoid:

struct xiiSimulationEntry
{
  xiiSimulation* m_pSimulation = nullptr;

  // Ownership is unspecified.
  // The caller may not know who destroys the simulation.
};

An owning raw pointer may be required when interacting with a specialized allocator or legacy interface, but its ownership contract MUST be explicit and consistently enforced.

Shared Ownership

Shared ownership introduces additional costs and lifetime complexity.

These may include:

• Reference-counting operations.
• Atomic synchronization or contention.
• Delayed and less predictable destruction.
• Ownership cycles.
• Difficulty coordinating resource release with subsystem shutdown.
• Resources remaining alive beyond plugin or device lifetime.

Shared ownership SHOULD NOT be the default solution to lifetime uncertainty.

When an object has one authoritative manager, prefer manager-owned storage and non-owning, validated access where appropriate.

Guiding principle:

Every resource must have an accountable owner. Borrowing grants access, not ownership, and shared ownership must reflect an actual lifetime requirement.

6.2 Allocation and Allocator Compatibility

XII’s allocation mechanisms MUST be used consistently with the allocator responsible for the resource.

The mechanism used to destroy an object must be compatible with the mechanism used to construct it.

General Requirements

• Use XII allocation facilities when required by the owning subsystem.
• Allocations made using XII_NEW MUST be released using the corresponding compatible XII destruction mechanism.
• Do not arbitrarily mix XII_NEW and XII_DELETE with unrelated C++ new and delete operations.
• Use XII_DEFAULT_NEW and XII_DEFAULT_DELETE to use the default allocator when no other allocator is required by the owning subsystem.
• Objects created through custom allocators MUST retain or otherwise have access to the allocator required for destruction.
• Containers SHOULD use the allocator associated with their owning subsystem when allocator selection is part of that subsystem’s contract.
• Avoid introducing independent allocations when values can be stored directly without compromising lifetime or address stability.
• Allocator ownership and lifetime MUST be compatible with the lifetime of every allocation obtained from it.
• Memory MUST NOT be released through an allocator that has already been destroyed or invalidated.
• Cross-module allocations MUST respect the allocation and destruction contract of the module boundary.

Example:

xiiUniquePtr<xiiSimulationData> pData = XII_DEFAULT_NEW(xiiSimulationData);

The example assumes the XII ownership wrapper and allocation macro support the corresponding allocator-aware construction and destruction semantics.

Explicit Allocator Dependencies

When an object requires a particular allocator, prefer expressing that dependency through its constructor or initialization contract.

Prefer:

class xiiSimulationStorage
{
public:
  explicit xiiSimulationStorage(xiiAllocator* pAllocator) :
    m_Entries(pAllocator)
  {
    XII_ASSERT_DEV(pAllocator != nullptr, "A valid allocator is required.");
  }

private:
  xiiDynamicArray<xiiUInt32> m_Entries;
};

Avoid:

class xiiSimulationStorage
{
public:
  xiiSimulationStorage() :
    m_Entries(GetGlobalSimulationAllocator())
  {
  }

private:
  xiiDynamicArray<xiiUInt32> m_Entries;
};

The avoided implementation introduces a hidden dependency on global allocator state.

A global or subsystem allocator may be appropriate when it is part of an established engine-wide allocation policy. However, allocator dependencies should not be hidden when explicit selection is necessary for correctness, testing, or lifetime management.

Allocator Lifetime

An allocator must remain valid until all allocations that depend on it have been released.

This requirement is particularly important for:

• Frame and temporary allocators.
• Pool and arena allocators.
• Plugin-specific allocators.
• Module-local heaps.
• Device-scoped resource allocators.
• Memory shared across dynamically loaded modules.

Resetting an arena or destroying a pool invalidates allocations owned by that allocator according to its documented semantics.

Guiding principle:

Allocation and destruction are a single ownership contract. The allocator, allocation, and owning object must have compatible lifetimes.

6.3 Borrowing Is Not Ownership

A borrowed pointer, reference, or view provides temporary access to an object according to the owner’s lifetime contract.

Borrowing MUST NOT be interpreted as ownership transfer or a guarantee that the referenced object will remain alive indefinitely.

General Requirements

• Borrowed access MUST remain within the validity period guaranteed by the owner.
• A borrowed pointer MUST NOT be destroyed by the borrower unless ownership transfer is explicitly documented.
• Borrowed access MUST NOT be retained beyond owner destruction or resource invalidation.
• Borrowed access MUST NOT be assumed thread-safe.
• Do not capture borrowed pointers in asynchronous operations without guaranteeing the referenced object’s lifetime.
• Do not expose borrowed references when their validity cannot be adequately described or enforced.
• Prefer references when null is not a meaningful state and the lifetime contract permits reference semantics.
• Prefer pointers when optional access, nullability, or reseating is meaningful.

Example:

xiiGALDevice* pDevice = m_pDevice.Borrow();

if (pDevice == nullptr)
  return XII_FAILURE;

InitializeDeviceResources(*pDevice);

The pointer is valid only while the owning object guarantees the device’s lifetime.

The Borrow() operation does not extend that lifetime.

Borrowing Across Asynchronous Boundaries

Borrowed access becomes particularly dangerous when execution is deferred.

Avoid:

void SubmitTask()
{
  xiiString sMessage = "Simulation complete";

  QueueTask([&sMessage]()
  {
    LogMessage(sMessage);
  });
}

The callback may execute after sMessage has been destroyed.

Prefer:

void SubmitTask()
{
  xiiString sMessage = "Simulation complete";

  QueueTask([sMessage = std::move(sMessage)]()
  {
    LogMessage(sMessage);
  });
}

The callback owns its captured string, assuming the task system stores and executes the callable according to the required ownership contract.

Copying or moving captured data is not always necessary. Borrowing remains appropriate when the asynchronous operation’s completion is guaranteed before the referenced storage becomes invalid.

Guiding principle:

Borrowed access is valid only for the lifetime and synchronization guarantees explicitly provided by its owner.

6.4 Stable Identity Is Not Stable Address

Object identity and memory address are distinct concepts.

A handle identifies a logical object through an authoritative subsystem, while a pointer identifies a particular memory location.

Neither mechanism automatically guarantees the continued lifetime of the referenced object.

General Requirements

• Use handles when objects require independently managed identity, validation, or generation tracking.
• Use pointers and references when direct access is appropriate and their lifetime is guaranteed.
• Do not assume that a container preserves element addresses unless its contract explicitly guarantees that behavior.
• Container growth, insertion, removal, compaction, or relocation MUST be considered when storing pointers or references to elements.
• Generation-checked handles SHOULD be used when reusable registry slots could otherwise allow stale identifiers to reference unrelated objects.
• Handle validity MUST be checked when the calling contract does not guarantee validity.
• Stable allocation addresses MUST NOT be confused with permanent resource validity.
• Handles MUST NOT be treated as ownership tokens unless the subsystem explicitly defines them that way.

Avoid:

xiiDynamicArray<Entry> m_Entries;

xiiIdTable<GraphId, Entry*, xiiLocalAllocatorWrapper> m_EntryTable;

// Pointers into m_Entries may be invalidated when
// the container reallocates or relocates its elements.

Prefer when stable allocation addresses are required:

xiiDynamicArray<xiiUniquePtr<Entry>> m_Entries;

// Moving or growing the pointer container does not
// relocate the independently allocated Entry objects.

This representation preserves the addresses of surviving allocated entries during relocation of the container’s pointer elements.

It does not preserve references after the corresponding entry is destroyed.

Handles and Generations

A generation-checked handle generally combines a resource slot or index with information that distinguishes different lifetimes of that slot.

When a resource is destroyed, its previous generation becomes invalid according to the registry’s rules.

This prevents certain stale-handle errors, including accidental access to a newly allocated object that reuses an earlier slot.

However, generation tracking does not automatically provide:

• Thread-safe lookup.
• Atomic lifetime acquisition.
• Protection against concurrent destruction after lookup.
• Protection against generation wraparound.
• Ownership of the referenced resource.

These guarantees require separate mechanisms.

Guiding principle:

Handles preserve logical identity through validation. Pointers provide direct access to memory. Neither alone establishes a lifetime or concurrency guarantee.

6.5 Lifetime-Safe Lookup and Concurrent Access

A successful resource lookup does not necessarily guarantee that the resource remains alive after the lookup completes.

This is especially important when registration, lookup, and destruction may occur concurrently.

General Requirements

• Resource lookup MUST respect the synchronization contract of the owning registry.
• A lookup mutex MUST NOT be assumed to protect a resource after the lock has been released.
• Returned pointers and references MUST remain valid for the documented duration of access.
• Resource destruction MUST NOT race with active access that requires the resource to remain alive.
• Lookup and lifetime protection MUST be coordinated when concurrent destruction is permitted.
• Do not return unrestricted mutable access to internally synchronized resources unless callers receive an enforceable synchronization contract.
• Thread-affine registries MUST document their permitted access and mutation contexts.
• Avoid introducing shared ownership solely for lookup convenience when scoped access or execution-boundary guarantees are sufficient.

Avoid:

Entry* GetEntry(xiiResourceHandle hResource)
{
  XII_LOCK(m_Mutex);

  Entry* pEntry = nullptr;
  m_ResourceTable.TryGetValue(hResource, pEntry);

  return pEntry;
}

The mutex protects the lookup operation, but it does not necessarily protect the returned pointer.

Another thread may destroy the entry immediately after the function releases the mutex.

Valid Lifetime Strategies

The appropriate strategy depends on the subsystem’s concurrency and execution model.

Common approaches include:

1. Scoped locking: Hold the required lock throughout the operation that accesses the resource.
2. Scoped access guards: Return an object that maintains the necessary lifetime and synchronization protection.
3. Shared ownership: Retain a strong ownership reference for the duration of access when shared lifetime semantics are appropriate.
4. Execution-boundary mutation: Permit registration and destruction only at defined synchronization points.
5. Deferred reclamation: Delay physical destruction until all active readers or operations have completed.

These strategies are alternatives rather than mechanisms that must all be implemented.

The simplest approach satisfying the actual concurrency requirements SHOULD be preferred.

Scoped Access

When resource access must remain synchronized, prefer an API that performs the operation within the required lifetime boundary.

For example:

xiiResult UpdateResource(xiiResourceHandle hResource)
{
  XII_LOCK(m_Mutex);

  Entry* pEntry = nullptr;

  if (!m_ResourceTable.TryGetValue(hResource, pEntry))
    return XII_FAILURE;

  return pEntry->Update();
}

This pattern is appropriate when the mutex protects the entire operation and Update() does not violate the lock’s reentrancy, ordering, or contention requirements.

Long-running operations should not automatically execute while holding a global registry mutex.

Where that would cause unacceptable contention, use a more appropriate scoped lifetime mechanism.

Guiding principle:

A lookup establishes that an object existed at a particular moment. Safe access requires that its lifetime and synchronization guarantees remain valid throughout the operation.

6.6 Parent-Child and Subsystem Lifetimes

Resources frequently depend on other objects or subsystems for their operation and destruction.

These dependencies MUST be reflected in initialization and shutdown ordering.

General Requirements

• Dependent resources MUST be released before the infrastructure required for their destruction becomes unavailable.
• Initialization order SHOULD follow dependency direction.
• Shutdown order SHOULD reverse dependency order where appropriate.
• Explicit shutdown operations MUST prevent new work from acquiring resources that are being destroyed.
• Objects MUST NOT access dependencies after those dependencies have been destroyed or invalidated.
• Plugin-owned callbacks, delegates, and registrations MUST be removed before unloading the plugin code they reference.
• Background tasks MUST complete, cancel, or otherwise release their dependencies before the owning subsystem is destroyed.
• Shutdown MUST account for partially initialized subsystems.
• Avoid relying on unspecified static initialization or destruction order across translation units or dynamically loaded modules.

Dependency Ordering

For example, a rendering subsystem may have the following dependency hierarchy:

GAL Device
  └── Device Resource Cache
      └── Render Graph Resources
          └── Frame Execution State

If each child depends on its parent during destruction, shutdown must release the dependent objects before the required parent infrastructure.

A typical shutdown sequence would therefore release:

1. Active frame execution state.
2. Graph-specific resources.
3. Device-scoped caches.
4. The underlying GAL device.

The exact sequence depends on the actual ownership and synchronization contracts.

It must not be inferred solely from the visual hierarchy.

Plugin Lifetime

Dynamically loaded plugins introduce an additional dependency: executable code may disappear when the module is unloaded.

Before unloading a plugin, the engine MUST ensure that no active operation retains a callback, virtual dispatch target, function pointer, or other executable reference into the unloaded module.

This includes asynchronous tasks and deferred callbacks that may execute after the plugin’s shutdown function returns.

Guiding principle:

Dependencies must outlive every operation that relies on them. Initialization establishes those dependencies; shutdown must dismantle them safely.

6.7 Resource Invalidation and Destruction

Resource invalidation MUST distinguish between invalidating a caller’s reference, removing a resource from a registry, and physically destroying its underlying allocation.

These events may occur at different times.

General Requirements

• Public handles SHOULD be invalidated after successful destruction when the API supports explicit invalidation.
• Invalidating one handle variable MUST NOT be interpreted as invalidating copies held elsewhere.
• The authoritative registry MUST reject handles that are stale according to its generation and validity rules.
• Destruction operations MUST preserve registry consistency.
• Resource removal MUST prevent future lookups from acquiring access when the resource is no longer logically available.
• Physical destruction MUST respect outstanding references and asynchronous execution dependencies.
• Repeated destruction attempts MUST have documented behavior.
• Failed destruction operations MUST leave resource ownership and validity in a documented state.

Example:

if (DestroyResource(hResource).Succeeded())
{
  hResource.Invalidate();
}

The caller invalidates its local handle only after the destruction operation reports success.

This does not revoke other copies of the handle.

The resource registry remains responsible for rejecting stale identifiers.

Logical and Physical Destruction

In asynchronous systems, resource destruction may involve multiple phases:

1. Logical invalidation: The resource becomes unavailable for new operations.
2. Retirement: Existing operations are allowed to complete or release their references.
3. Physical destruction: The underlying allocation and associated objects are released.

Not every subsystem requires all three phases.

A simple CPU-owned object with no outstanding references may be destroyed immediately.

GPU resources, asynchronously accessed objects, and concurrently readable registry entries may require deferred reclamation.

Guiding principle:

Invalidating a reference prevents future intended use. Safe destruction additionally requires that no outstanding operation can still access the resource.

6.8 Non-Owning Views and Scope-Bound Data

Views, spans, borrowed strings, iterators, mapped memory, and similar abstractions provide access without necessarily controlling the lifetime of the referenced storage.

Their validity MUST remain within the lifetime and invalidation guarantees of the underlying owner.

General Requirements

• Non-owning views MUST NOT outlive their backing storage.
• Views MUST NOT be retained across container mutations that invalidate their referenced storage.
• Do not return views or references into temporary objects that are destroyed before the caller can use them.
• Do not persist borrowed stack storage in asynchronous callbacks or long-lived objects.
• Copy data into owning storage when its lifetime must extend beyond the original owner’s guarantees.
• Mapping objects and scoped access helpers MUST respect their required unmapping or release operations.
• Borrowed views MUST NOT be assumed safe for concurrent mutation.
• Prefer explicit ownership when lifetime extension cannot be guaranteed reliably.

Avoid:

xiiStringView MakeResourceName()
{
  xiiString sName = "SimulationResource";

  return sName;
}

The returned view references storage owned by a local string that is destroyed when the function returns.

Prefer:

xiiString MakeResourceName()
{
  return xiiString("SimulationResource");
}

The returned string owns its storage.

Container Invalidation

Container operations may invalidate references, pointers, iterators, or views into their contents.

Code MUST respect the invalidation guarantees of the specific container being used.

Do not assume that all XII containers share the same relocation or iterator stability semantics.

For example, growing a contiguous dynamic array may relocate its elements, invalidating previously obtained pointers.

A container providing stable element addresses may have different guarantees, but element removal still invalidates access to the removed object.

Scoped Mapping

Memory obtained through a mapping operation may remain valid only until its corresponding unmap or release operation.

Such pointers MUST NOT be retained beyond that boundary.

This applies to CPU memory mappings, GPU-visible mapped ranges, temporary allocator storage, and similar scoped resources.

Guiding principle:

A view grants access to existing storage; it does not extend the storage’s lifetime. Persist ownership, not borrowed access, when data must survive its original scope.

6.9 Runtime and GPU Resource Lifetimes

CPU-side execution completion and GPU execution completion are different events.

A function returning from command recording, submission, or render graph execution does not necessarily mean that the GPU has finished accessing the submitted resources.

GPU resource lifetime MUST account for asynchronous execution.

General Requirements

• CPU-side submission completion MUST NOT be treated as proof of GPU execution completion.
• Resources referenced by submitted GPU work MUST remain valid until the GPU has completed the operations that require them.
• Resource retirement MUST use appropriate queue completion, fence, timeline, or equivalent synchronization guarantees.
• Command allocators, descriptor storage, upload buffers, temporary resources, and other GPU-visible allocations MUST respect their actual in-flight lifetimes.
• Frame-index progression MUST NOT be confused with GPU completion unless the frame-management contract explicitly establishes that relationship.
• Resource reuse MUST respect outstanding GPU dependencies.
• Deferred destruction mechanisms MUST preserve the resources and associated device infrastructure required for final cleanup.
• Device shutdown MUST account for outstanding submissions and pending resource retirement.
• Synchronization mechanisms MUST follow the guarantees of the active graphics backend.

Submission Versus Completion

Consider a typical sequence:

CPU:
  Record Commands
        |
        v
  Submit Commands
        |
        v
  Execute() Returns
        |
        v
  Continue CPU Work

GPU:
        Execute Submitted Commands
                    |
                    v
              Signal Completion

The CPU may continue execution while the GPU is still processing previously submitted commands.

Destroying a resource immediately after the submission function returns may therefore be unsafe.

Deferred Resource Retirement

A rendering subsystem may logically release a resource immediately while retaining its physical allocation until the relevant GPU completion condition is satisfied.

For example:

void ReleaseResource(xiiGALResourceHandle hResource)
{
  QueueResourceRetirement(hResource, GetCurrentSubmissionValue());
}

This is a conceptual example. The retirement system must ensure that the recorded completion value covers every GPU submission that may still access the resource.

A resource may have dependencies across multiple queues or submissions. The last submission recorded by a local subsystem is not necessarily sufficient to establish safe destruction.

Frames in Flight

Frame-buffering strategies commonly retain resources across several in-flight frames.

However, a fixed number of frames in flight is not itself a completion guarantee.

Resource reuse and destruction MUST be based on the synchronization semantics of the frame system and graphics backend.

Do not assume that advancing a frame counter by a particular amount proves that earlier GPU work has completed.

Detailed GPU synchronization, queue completion, and retirement requirements are covered in §15.

Guiding principle:

CPU execution determines when work is submitted. GPU synchronization determines when its resources can be safely reused or destroyed. These lifetimes must never be conflated.

6.10 Initialization and Shutdown State Machines

Subsystem initialization and shutdown MUST follow a documented lifecycle.

A component should not require callers to infer which operations are valid from partially initialized internal state.

General Requirements

• Initialization and shutdown operations MUST define their valid calling conditions.
• Repeated initialization MUST have documented behavior.
• Repeated shutdown MUST either be supported safely or treated as an explicit contract violation.
• Initialization failures MUST leave the component in a state where cleanup or recovery is possible.
• Shutdown MUST prevent new work from accessing resources that are being retired.
• Lifecycle state SHOULD remain minimal and correspond to actual observable requirements.
• Do not introduce elaborate state machines for simple components that require only initialized and uninitialized states.
• Explicit initialization methods SHOULD return xiiResult when initialization may fail for expected runtime reasons.

Example:

class xiiSubsystem
{
public:
  xiiResult Initialize()
  {
    if (m_bInitialized)
      return XII_FAILURE;

    if (InitializeResources().Failed())
      return XII_FAILURE;

    m_bInitialized = true;
    return XII_SUCCESS;
  }

  void Shutdown()
  {
    if (!m_bInitialized)
      return;

    ReleaseResources();
    m_bInitialized = false;
  }

  XII_ALWAYS_INLINE bool IsInitialized() const
  {
    return m_bInitialized;
  }

private:
  xiiResult InitializeResources();
  void ReleaseResources();

  bool m_bInitialized = false;
};

This example assumes InitializeResources() either cleans up any partial acquisitions before returning failure or leaves them in a state safely handled by the component’s cleanup contract.

The implementation must not mark initialization as complete before all required invariants have been established.

Transactional Initialization

Where practical, initialization SHOULD provide an all-or-nothing observable result.

If initialization fails, the subsystem should either:

• Restore its previous valid state.
• Return to a documented uninitialized state.
• Enter an explicit recoverable failure state when restoration is impossible or inappropriate.

Partial initialization must not leave resources permanently owned without a valid cleanup path.

Guiding principle:

Initialization establishes a usable state; shutdown dismantles it. Both operations must preserve ownership, invariants, and well-defined recovery behavior.

6.11 Asynchronous Operations and Cancellation

Asynchronous execution introduces lifetimes that may extend beyond the scope of the function that schedules the work.

Every asynchronous operation MUST establish ownership and cancellation rules for the data and resources it accesses.

General Requirements

• Captured objects MUST remain valid until asynchronous work completes or releases them.
• Cancellation MUST NOT be treated as synchronous completion unless the API explicitly guarantees it.
• Owners MUST coordinate outstanding tasks before destroying resources those tasks may access.
• Callbacks MUST NOT retain references to destroyed objects or unloaded plugin code.
• Task completion and resource release MUST obey the required synchronization and memory-visibility rules.
• Do not introduce shared ownership merely because an operation is asynchronous when scoped completion or explicit lifetime coordination provides a simpler solution.
• Asynchronous APIs SHOULD make ownership transfer and cancellation responsibilities visible.
• Shutdown paths MUST define how pending, executing, and completed tasks are handled.

Cancellation Versus Completion

Cancellation commonly represents a request that work should stop or avoid starting.

It does not necessarily guarantee that currently executing work has finished.

A component that requests cancellation and then immediately destroys task dependencies may therefore introduce use-after-free behavior.

Safe destruction may require waiting for task completion, transferring ownership of required data, or deferring reclamation.

Guiding principle:

Scheduling transfers work into the future, not automatically the ownership of everything that work accesses. Asynchronous lifetime guarantees must be explicit.

6.12 Resource Lifetime Verification

Lifetime correctness SHOULD be validated through tests and development diagnostics, particularly for resource managers, concurrent registries, asynchronous execution, and device-scoped resources.

General Requirements

• Test initialization failure and partial cleanup paths where recoverable failures are possible.
• Verify that repeated cleanup does not violate the documented lifecycle contract.
• Test stale-handle rejection when generation-checked handles are used.
• Exercise container growth, removal, and relocation when references to stored elements are retained.
• Validate concurrent lookup and destruction when the subsystem permits those operations.
• Test subsystem shutdown with outstanding work when asynchronous execution is supported.
• Verify that plugin shutdown removes callbacks and registrations before unloading.
• Exercise GPU resource retirement under representative frames-in-flight and queue synchronization conditions.
• Use assertions and diagnostic instrumentation to detect violated ownership and lifetime contracts during development.
• Do not rely exclusively on assertions to prevent invalid resource access in production execution.

Relevant tests SHOULD focus on the actual lifetime guarantees of the component rather than merely confirming that normal construction and destruction succeed.

Guiding principle:

Ownership and lifetime guarantees are correctness properties. They should be explicit in interfaces, enforced by implementations, and verified under failure, concurrency, and shutdown conditions.

7. Functions, Parameters, and Return Values

Functions in XII MUST express clear responsibilities, communicate their contracts through their interfaces, and preserve predictable behavior across supported platforms and configurations.

Function signatures should make dependencies, ownership, mutability, failure behavior, and observable side effects apparent wherever practical.

This section extends the principles established in §1.1 (Correctness), §1.2 (Ownership and Lifetime), §1.3 (Interface Design), §3 (Naming Conventions), and §5 (Types and Interfaces).

7.1 Functions Should Perform One Coherent Operation

A function SHOULD perform one coherent operation at a consistent level of abstraction.

This does not require every function to contain only a few statements. A substantial implementation may remain appropriate when its operations collectively fulfill one clearly defined responsibility.

General Requirements

• Functions MUST have a clearly identifiable purpose.
• Prefer separating operations with distinct failure, ownership, synchronization, or lifecycle semantics.
• Do not combine unrelated responsibilities merely to reduce the number of functions.
• Avoid extracting trivial wrappers that introduce navigation overhead without establishing a meaningful boundary.
• Functions SHOULD operate at a consistent level of abstraction.
• Prefer meaningful helper functions when they isolate reusable logic, enforce invariants, or clarify complex algorithms.
• Avoid excessive parameter lists when they indicate that a function performs unrelated operations or depends on too much external state.
• Do not split tightly coupled operations when doing so would expose invalid intermediate states or compromise correctness.
• Function names MUST accurately describe the work performed and its observable effects.

Prefer:

xiiResult LoadDocument(xiiStringView sPath);
xiiResult ValidateDocument();
xiiResult SaveDocument(xiiStringView sPath);

Each operation has a distinct responsibility and may encounter different failure conditions.

A higher-level operation may coordinate these steps when appropriate:

xiiResult OpenDocument(xiiStringView sPath)
{
  XII_SUCCEED_OR_RETURN(LoadDocument(sPath));
  XII_SUCCEED_OR_RETURN(ValidateDocument());

  return XII_SUCCESS;
}

The coordinating function remains cohesive because its responsibility is opening a valid document.

Avoid Excessive Fragmentation

Do not extract every expression into a separate function merely to reduce function length.

A helper function should provide at least one meaningful benefit:

• Encapsulation of a distinct responsibility.
• Reuse by multiple consumers.
• Enforcement of an invariant.
• Clarification of a complex algorithm.
• Isolation of platform-specific behavior.
• Separation of independently testable logic.
• Establishment of a meaningful failure or synchronization boundary.

Function length alone MUST NOT determine whether an implementation should be divided.

Guiding principle:

A function should perform one coherent operation, but cohesion matters more than line count.

7.2 Prefer Explicit Inputs and Dependencies

Functions SHOULD receive the information required for their operation through explicit parameters, object state, or clearly documented subsystem dependencies.

Avoid hidden mutable global state when an explicit dependency would improve correctness, reuse, or testability.

General Requirements

• Required inputs SHOULD be apparent from the function signature or the owning object’s documented state.
• Avoid retrieving mutable global state when the caller already possesses the required context.
• Do not introduce hidden dependencies on the active frame, current thread, global device, or singleton unless those dependencies are part of an established subsystem contract.
• Functions SHOULD NOT silently depend on unrelated initialization or execution state.
• Prefer passing the narrowest context required by the operation.
• Do not pass entire subsystem objects when only a small, well-defined portion of their capabilities is required, unless doing so is consistent with the architecture.
• Avoid introducing unnecessary parameter forwarding through multiple layers when the dependency naturally belongs to an owning component.
• Execution context MUST remain valid throughout the operation.

Prefer:

xiiResult Simulate(xiiSimulationWorld& world, const xiiSimulationSettings& settings, xiiTime deltaTime);

Avoid:

xiiResult Simulate()
{
  auto* pWorld    = GetGlobalActiveWorld();
  auto* pSettings = GetGlobalSimulationSettings();

  // Hidden dependencies on mutable global state.
}

The preferred interface makes its dependencies explicit and allows the operation to be invoked in different simulation contexts.

Callback and Delegate Context

Callbacks and delegates MUST receive or safely capture the context required for their execution.

For example:

using SimulationDelegate = xiiDelegate<void(xiiSimulationWorld&, const xiiSimulationSettings&, xiiTime)>;

A delegate MUST NOT retain borrowed references beyond their guaranteed lifetime.

When callbacks execute asynchronously or survive subsystem transitions, their captured ownership and executable-code lifetime must follow §6.11.

Guiding principle:

Dependencies should be visible at the boundary where they matter. Hidden state should not determine behavior that callers reasonably expect to control.

7.3 Parameter Passing

Parameter types MUST accurately express input semantics, mutability, optionality, and ownership.

Choose parameter-passing mechanisms according to the type’s size, semantics, lifetime requirements, and intended use.

General Requirements

• Prefer pass-by-value for inexpensive value-like types.
• Avoid copying large objects when borrowed access is sufficient.
• Use const references for read-only access to objects that are expensive or inappropriate to copy.
• Use mutable references only when mutation is part of the function’s contract.
• Prefer references for required objects and pointers for optional objects, unless existing API conventions establish different semantics.
• Do not use non-const references merely to avoid copying when the function does not modify the argument.
• Do not use output parameters when a direct return value is simpler and communicates the result adequately.
• Ownership transfer MUST be explicit and consistent with the owning type.
• Non-owning parameter views MUST NOT be retained beyond their documented lifetime.
• Parameter types SHOULD avoid unnecessarily constraining callers to a particular container implementation.

Prefer:

xiiResult CalculateBounds(xiiArrayPtr<const xiiVec3> positions, xiiBoundingBox& out_Bounds);

This signature communicates that the function reads the positions and writes the resulting bounding box.

Pass-by-Value Versus References

Pass-by-value is not automatically faster for every small type.

Calling conventions, alignment, register availability, and the type’s copy semantics can affect performance.

For mathematical and SIMD types, follow established XII conventions and measured performance requirements.

Do not mechanically replace const T& with T based solely on sizeof(T).

Guiding principle:

Parameter types should communicate how data is used, whether it may change, and whether its ownership is transferred.

7.4 Output and Input/Output Parameters

Output parameters SHOULD use descriptive names that distinguish produced values from ordinary inputs.

XII commonly uses the out_ and inout_ naming conventions. These are recommended documentation conventions rather than mandatory type-dependent prefix requirements for all parameters.

Naming Conventions

• Use out_ for parameters whose primary purpose is to receive a produced value.
• Use inout_ for parameters whose existing value is intentionally read and modified.
• Names SHOULD retain applicable type-dependent prefixes after the direction marker.
• Do not use output-direction prefixes for parameters that are merely mutable implementation details.
• Output parameters MUST have documented validity guarantees on success and failure.
• Prefer direct return values when the function produces one simple result and does not require independent failure reporting.

Example:

xiiResult GetTaskCompletion(xiiTaskHandle hTask, xiiUInt64& out_uiCompletionValue);

For an input/output parameter:

void NormalizeWeights(xiiArrayPtr<float> inout_Weights);

Failure Semantics

When a function returns xiiResult and also writes output parameters, the contract MUST establish whether those outputs are modified when the operation fails.

Where practical, prefer leaving output parameters unchanged on failure.

Prefer:

xiiResult ParseCount(xiiStringView sText, xiiUInt32& out_uiCount)
{
  xiiUInt32 uiParsedCount = 0U;

  XII_SUCCEED_OR_RETURN(ParseUnsignedInteger(sText, uiParsedCount));

  out_uiCount = uiParsedCount;
  return XII_SUCCESS;
}

The output is committed only after parsing succeeds.

This provides a clear failure guarantee without requiring the caller to inspect partially modified output state.

Multiple Outputs

Several related output values may indicate that a small result structure would provide a clearer interface.

However, do not introduce a new structure merely to eliminate two straightforward output parameters.

Choose the representation that best communicates the operation’s contract.

Guiding principle:

Output parameters must make data flow and failure behavior explicit. Prefer committing observable changes only after successful completion when practical.

7.5 const Correctness

const correctness MUST be maintained throughout function interfaces and implementations.

Read-only access should be expressed through the type system wherever practical.

General Requirements

• Member functions that do not modify observable object state SHOULD be marked const.
• Read-only reference parameters SHOULD use const T&.
• Read-only pointer parameters SHOULD use const T*.
• Avoid exposing mutable access through const interfaces unless the operation has a justified logical-constness contract.
• Do not use const_cast to bypass interface restrictions without a concrete and documented reason.
• Prefer immutable local values when reassignment is unnecessary and immutability improves clarity.
• Use mutable only for members whose modification is compatible with the type’s logical constness.
• A const member function MUST NOT be assumed thread-safe solely because it is declared const.

Prefer:

class xiiSimulationClock
{
public:
  XII_ALWAYS_INLINE xiiUInt64 GetStepCount() const
  {
    return m_uiStepCount;
  }

private:
  xiiUInt64 m_uiStepCount = 0U;
};

Logical Constness

A const method may legitimately update internal implementation details, such as a cache or statistics counter, when those changes do not violate the method’s observable contract.

Such mutation MUST remain safe under the type’s concurrency guarantees.

For example, lazily populating a mutable cache inside a const function can introduce data races if multiple threads invoke the function concurrently.

Shallow Constness

const qualification does not necessarily make all indirectly referenced objects immutable.

A const smart pointer or const container holding pointers may still permit mutation of the pointed-to objects, depending on its API.

Interfaces MUST consider the actual mutability of reachable state rather than relying exclusively on top-level const.

Guiding principle:

Use const to express permitted mutation accurately, but do not confuse logical immutability with thread safety or transitive immutability.

7.6 [[nodiscard]] and Return-Value Significance

Return values that communicate failure, ownership, identity, or other correctness-critical information SHOULD be marked [[nodiscard]].

The attribute helps identify accidental result omission but does not replace explicit error-handling contracts.

General Requirements

• Functions returning a failure-sensitive result SHOULD use [[nodiscard]] where the relevant result type is not already annotated.
• Resource creation functions returning owning objects or handles SHOULD use [[nodiscard]].
• Functions returning values whose omission would likely indicate a programming error SHOULD use [[nodiscard]].
• Do not apply [[nodiscard]] mechanically to every trivial getter without considering existing API conventions.
• Do not suppress return-value diagnostics merely to satisfy compilation.
• If ignoring a result is intentional, use the established mechanism and ensure that doing so is safe under the operation’s contract.
• [[nodiscard]] MUST NOT be treated as a guarantee that callers cannot discard the result.

Prefer:

xiiResult InitializeSubsystem(); // xiiResult is [[nodiscard]] by convention.

[[nodiscard]] xiiResourceHandle CreateResource(const xiiResourceDescriptor& descriptor);

[[nodiscard]] bool IsResourceValid(xiiResourceHandle hResource) const;

An operation returning an important result should make its expected usage apparent.

Type-Level Attributes

If xiiResult or another return type is already annotated with [[nodiscard]], repeating the attribute on every function may be unnecessary.

Contributors SHOULD follow the conventions established by the relevant XII type and surrounding APIs.

Guiding principle:

Important return values should be difficult to ignore accidentally. The type system and compiler diagnostics should reinforce explicit handling.

7.7 Results, Failures, and Error Propagation

Expected runtime failures MUST be represented through explicit error mechanisms, consistent with §1.1.

xiiResult is appropriate when an operation needs to communicate success or failure without returning detailed error information directly.

General Requirements

• Functions that may legitimately fail MUST provide an observable failure mechanism.
• Failure-sensitive results MUST NOT be silently discarded.
• Check operation results before executing dependent operations.
• Prefer early failure propagation when the current function cannot meaningfully recover.
• Use established XII result macros and methods where they improve clarity.
• Do not return XII_SUCCESS unless the operation has fulfilled its documented success conditions.
• Error logging SHOULD occur where sufficient diagnostic context exists.
• Avoid logging the same failure repeatedly at every propagation layer.
• Do not use xiiResult to conceal programming errors or violated API preconditions.
• Failure paths MUST preserve the documented invariants and cleanup guarantees of the owning component.

Prefer:

xiiResult LoadConfiguration(xiiStringView sPath)
{
  xiiFileReader file;

  XII_SUCCEED_OR_RETURN(file.Open(sPath));

  return ParseConfiguration(file);
}

Result Propagation

Use XII_SUCCEED_OR_RETURN when the called operation’s failure can be propagated without additional handling.

XII_SUCCEED_OR_RETURN(InitializeStorage());
XII_SUCCEED_OR_RETURN(LoadResources());
XII_SUCCEED_OR_RETURN(ValidateState());

When additional diagnostic information or recovery behavior is required, use an explicit check.

if (LoadConfiguration(sPath).Failed())
{
  xiiLog::Error("Failed to load configuration from '{0}'.", sPath);
  return XII_FAILURE;
}

Ignoring Results

Use .IgnoreResult() only when intentionally discarding the result is permitted by the operation’s contract.

Avoid:

SaveConfiguration(sPath).IgnoreResult();

// A required save may have failed silently.

Ignoring a result can be appropriate when failure is genuinely inconsequential or explicitly handled through another mechanism.

Such decisions SHOULD be clear from the surrounding implementation or documented where necessary.

Rich Error Information

xiiResult communicates success or failure but does not inherently carry a detailed failure reason.

When callers need structured diagnostics, error categories, partial results, or recovery information, use an appropriate result structure or explicit error output.

Do not introduce an elaborate generic error framework when a simple xiiResult and contextual diagnostic are sufficient.

Guiding principle:

Failure is part of an operation’s contract. Propagate it explicitly, preserve invariants, and report useful diagnostics without unnecessary complexity.

7.8 Default Arguments

Default arguments SHOULD represent common, safe, and unsurprising behavior.

They are appropriate when omitting an argument has a stable meaning that is understandable from the function’s name and contract.

General Requirements

• Default arguments MUST preserve valid behavior.
• Defaults SHOULD represent the most common or least surprising operation.
• Avoid defaults that depend on hidden mutable state or ambiguous execution context.
• Do not use default arguments to conceal required dependencies.
• Avoid long parameter lists containing multiple unrelated defaulted values.
• Boolean parameters SHOULD be avoided when their meaning is unclear at the call site.
• Prefer a configuration structure when an operation has several independently configurable options.
• Changes to public default arguments MUST consider source compatibility and behavioral effects on existing callers.
• Default arguments MUST NOT be redeclared inconsistently across declarations.

Prefer:

xiiResult StartSimulation(xiiUInt32 uiMaxIterations = 128U);

Avoid:

StartSimulation(true, false, true, 128U);

The latter obscures the purpose of each boolean argument.

Configuration Structures

When several independent options are required, a configuration structure can provide clearer call sites and allow future extension.

Prefer:

struct xiiSimulationOptions
{
  bool      m_bEnableTracing    = false;
  bool      m_bAllowParallelism = true;
  xiiUInt32 m_uiMaxIterations   = 128U;
};

xiiResult StartSimulation(const xiiSimulationOptions& options);

However, do not introduce a configuration structure for every function with two or three clearly understood parameters.

Default Arguments and Virtual Functions

Default arguments are resolved statically according to the declaration visible at the call site, while virtual dispatch selects the implementation dynamically.

Therefore, default arguments SHOULD NOT differ across overrides.

Where virtual interfaces require default behavior, consider a non-virtual convenience wrapper that delegates to the virtual operation with explicit arguments.

Guiding principle:

Defaults should simplify common use without concealing meaning, dependencies, or behavioral differences.

7.9 Overloads and Operation Semantics

Function overloads SHOULD represent the same conceptual operation applied to different supported argument forms.

Do not use overloads to conceal significantly different behavior, ownership requirements, or side effects.

General Requirements

• Overloads MUST preserve a coherent semantic relationship.
• Functions with substantially different responsibilities SHOULD use distinct names.
• Overloads MUST NOT unexpectedly change ownership transfer or lifetime semantics.
• Avoid overload sets that create ambiguous conversions or surprising overload resolution.
• Do not introduce overloads solely to avoid explicit conversions when those conversions clarify intent.
• Prefer consistent failure and return-value semantics across related overloads.
• Overload implementations SHOULD share a common implementation where doing so reduces duplication without introducing unnecessary indirection.
• Changes to overload sets MUST consider their effects on existing call sites and implicit conversions.

Prefer:

xiiResult LoadResource(xiiStringView sPath);
xiiResult LoadResource(const xiiResourceDescriptor& descriptor);

Both functions perform resource loading using different forms of input.

Avoid:

void Process(xiiResourceHandle hResource);
void Process(xiiUInt32 uiMilliseconds);

The two operations have unrelated meanings despite sharing a name.

Lifecycle Semantics

An operation named ExecuteTask() should not implicitly initialize an entire task system or advance an unrelated scheduler unless that behavior is part of its documented contract.

Prefer distinct operations for distinct lifecycle stages.

Guiding principle:

Overloading should provide alternative ways to perform the same operation, not hide unrelated behavior behind a common name.

7.10 noexcept and Exception Boundaries

XII does not permit C++ exceptions for ordinary engine error handling.

Expected failures MUST be represented through explicit mechanisms such as xiiResult, error outputs, or appropriately designed result types.

Exceptions may be encountered within deeply isolated platform or third-party integration code where their use is unavoidable. Such exceptions must not escape into ordinary engine-facing APIs.

General Requirements

• Engine-facing functions MUST NOT use exceptions to communicate expected runtime failures.
• Do not introduce throw expressions into ordinary engine code.
• Use noexcept only when the operation can satisfy the exception guarantee under its supported execution environments.
• Do not annotate functions noexcept merely because the current compiler configuration disables exceptions.
• Functions marked noexcept MUST NOT permit exception propagation from platform or third-party operations.
• Exception-generating dependencies MUST be isolated at appropriate integration boundaries.
• Where exception handling is available and unavoidable, caught failures SHOULD be translated into the engine’s established error-reporting mechanisms.
• Destructors MUST NOT propagate exceptions.
• Do not use exception specifications as substitutes for documenting ordinary failure behavior.

Platform Exception Boundaries

Where a third-party or platform API may throw exceptions, the integration layer should contain the exception mechanism when the build configuration supports catching those exceptions.

The translated failure should be returned through an ordinary engine-compatible mechanism.

If the relevant environment does not permit exception handling, the integration must use an appropriate non-throwing API or another explicitly supported boundary strategy.

Guiding principle:

Expected failures are explicit results. Exception behavior, when unavoidable, must remain isolated from ordinary XII engine contracts.

7.11 Returning References, Pointers, and Views

Returned pointers, references, and views MUST have clear validity and invalidation guarantees.

A returned reference communicates access, not ownership.

The relevant lifetime and borrowing requirements are established in §§1.2 and 6.3–6.8.

General Requirements

• Never return references or views into local temporary storage.
• Returned borrowed access MUST remain valid for the documented duration.
• Do not return mutable references to internal state when doing so permits callers to violate invariants.
• Prefer returning small value-like objects directly when copying is inexpensive.
• Use handles when independently managed identity and validation are required.
• Do not return pointers into containers without considering relocation and removal invalidation.
• Access to shared mutable objects MUST respect their synchronization requirements.
• Prefer scoped access or controlled operations when a returned pointer cannot safely outlive an internal lock.
• Do not expose borrowed access across asynchronous boundaries without sufficient lifetime guarantees.

Avoid:

const xiiString& GetName() const
{
  xiiString sName = BuildName();
  return sName;
}

The returned reference refers to an object destroyed when the function returns.

Prefer:

xiiString GetName() const
{
  return BuildName();
}

Returning an owning value avoids the lifetime violation.

Internal Storage

Returning references to internal storage may be appropriate for stable, read-only access when the owning object’s lifetime and invalidation rules are explicit.

However, a const reference is not automatically safe if another thread can mutate or destroy the referenced object.

Guiding principle:

Returned access must remain valid for as long as callers are permitted to use it. Ownership, invalidation, and concurrency guarantees must be explicit.

7.12 Inline and Force-Inline Functions

Inlining decisions SHOULD be based on language requirements, implementation clarity, and demonstrated performance needs.

The inline keyword and compiler-specific force-inline mechanisms serve different purposes and must not be treated as interchangeable guarantees.

General Requirements

• Use ordinary inline where required for header-defined non-template functions with external linkage.
• Small, stable accessors MAY be defined directly within class declarations.
• Non-trivial non-template implementations SHOULD remain in .cpp files unless header placement is justified.
• Use XII_ALWAYS_INLINE sparingly and consistently with established performance-sensitive code.
• Do not assume that ordinary inline guarantees machine-code inlining.
• Do not use force-inlining to compensate for inefficient algorithms or unnecessary abstraction layers.
• Avoid excessive header-defined implementation code that increases compilation time and dependency propagation.
• Performance-motivated force-inlining SHOULD be supported by measurements, consistent with §1.5.
• Inlining decisions MUST NOT violate linkage, One Definition Rule (ODR), or binary interface requirements.

Prefer:

class xiiTaskCounter
{
public:
  XII_ALWAYS_INLINE xiiUInt32 GetCount() const
  {
    return m_uiCount;
  }

private:
  xiiUInt32 m_uiCount = 0U;
};

The accessor is trivial and suitable for a header definition.

For larger implementations, prefer ordinary out-of-line definitions.

Force-Inlining Trade-offs

Force-inlining may reduce call overhead in appropriate hot paths, but it can also:

• Increase generated code size.
• Increase instruction-cache pressure.
• Increase compilation time.
• Duplicate substantial implementation code.
• Prevent the compiler from making more effective code-size trade-offs.

An aggressively inlined implementation is not necessarily faster.

Guiding principle:

Inline for correctness and clarity where required; force-inline only when the performance benefit justifies the cost.

7.13 Function Preconditions and Postconditions

Function contracts MUST distinguish required preconditions from expected runtime failures.

A precondition describes what must be true for a valid call. A postcondition describes the guarantees established after an operation completes.

General Requirements

• Preconditions SHOULD be apparent from the interface or documented where they are not obvious.
• Contract violations SHOULD be detected through appropriate assertions or explicit enforcement mechanisms.
• Expected runtime failures MUST use the applicable error-reporting mechanism.
• Successful operations MUST establish their documented postconditions.
• Failed operations MUST preserve their documented failure guarantees.
• Do not use assertions as substitutes for validating untrusted input.
• Do not return XII_FAILURE for every programmer error merely to avoid defining correct API contracts.
• Functions MUST NOT silently accept invalid states that compromise internal invariants.

Example:

void SetCapacity(xiiUInt32 uiCapacity)
{
  XII_ASSERT_DEV(uiCapacity > 0U, "Capacity must be greater than zero.");

  m_uiCapacity = uiCapacity;
}

Here, a positive capacity is a programmer-facing precondition.

By contrast:

xiiResult LoadSettings(xiiStringView sPath)
{
  xiiFileReader file;

  XII_SUCCEED_OR_RETURN(file.Open(sPath));

  return ParseSettings(file);
}

File opening and parsing can fail during otherwise valid calls and therefore expose expected runtime failures.

Guiding principle:

Preconditions define valid calls. Results communicate expected failure. Postconditions define what callers may rely on after completion.

7.14 Side Effects and Observable Behavior

Function names and signatures SHOULD communicate meaningful side effects.

An operation’s observable behavior must be consistent with the expectations established by its interface.

General Requirements

• Query functions SHOULD NOT modify externally observable state unless their contract explicitly permits it.
• Functions that mutate state SHOULD use names that communicate the operation being performed.
• Do not conceal resource allocation, synchronization, scheduling, or substantial I/O behind apparently trivial accessors.
• Operations that may block for significant or unbounded periods SHOULD make that behavior apparent through their naming or documented contract.
• Avoid unexpected global state changes within functions that appear to operate on local data.
• Side effects MUST remain consistent across overloads that represent the same conceptual operation.
• Functions SHOULD avoid partially committing externally observable state before recoverable validation has completed.

Prefer:

bool IsTaskComplete(xiiTaskHandle hTask) const;

xiiResult WaitForTask(xiiTaskHandle hTask);

These names distinguish a non-blocking query from an operation that may wait.

Avoid:

bool GetTaskComplete(xiiTaskHandle hTask);

If the implementation also waits for the task to finish, its name conceals important execution behavior.

Guiding principle:

Callers should not need to inspect an implementation to discover consequential side effects.

7.15 Function Complexity and Reviewability

Functions SHOULD remain understandable as cohesive units of behavior.

Complexity should be controlled through appropriate decomposition, explicit state transitions, and meaningful abstraction boundaries rather than arbitrary limits on function length.

General Requirements

• Avoid deeply nested control flow when guard clauses or restructuring can simplify the implementation.
• Avoid functions that coordinate unrelated responsibilities or manipulate unrelated subsystem state.
• Prefer descriptive intermediate variables when they clarify non-obvious expressions.
• Do not introduce unnecessary temporaries or helpers that make straightforward logic harder to follow.
• Keep resource acquisition, use, and release relationships visible.
• Error paths SHOULD remain easy to follow and verify.
• Complex algorithms SHOULD document important invariants and non-obvious reasoning.
• Do not introduce generic abstractions solely to reduce apparent function complexity.
• Refactoring MUST preserve externally observable behavior unless a behavioral change is intentional.

A long function implementing one cohesive algorithm may be clearer than several tightly coupled functions that require readers to reconstruct control flow across multiple files.

Conversely, a short function may still be poorly designed if it combines unrelated responsibilities or conceals significant side effects.

Guiding principle:

Optimize functions for comprehension and correctness, not arbitrary line counts. Structure should reveal intent, dependencies, and failure behavior.

8. Control Flow and Expressions

Control flow and expressions in XII MUST be explicit, predictable, and correct across supported platforms, compilers, and execution environments.

Prefer straightforward branching, well-defined evaluation semantics, and mathematically sound operations over compact expressions that obscure program behavior.

Control-flow decisions should preserve the invariants established in §1.1, follow the statement conventions in §2.4, and respect the error-handling requirements in §7.7.

8.1 Prefer Early Exits and Guard Clauses

Guard clauses SHOULD be used to handle invalid inputs, unmet preconditions, and recoverable failures before entering the main body of an operation.

Early exits reduce unnecessary nesting and make the successful execution path easier to understand.

General Requirements

• Prefer early returns when they simplify control flow and make failure conditions immediately apparent.
• Validate untrusted inputs before using them in operations that require specific ranges or invariants.
• Distinguish programmer contract violations from expected runtime failures, as established in §1.1.
• Do not use deeply nested conditionals when guard clauses express the same behavior more clearly.
• Error paths MUST preserve resource ownership, synchronization, and cleanup guarantees.
• Prefer RAII for resources that require cleanup across multiple return paths.
• Do not introduce multiple early returns when they obscure a required common finalization step.
• Avoid redundant validation when a preceding operation already establishes the necessary invariant.

Prefer:

xiiResult ProcessDocument(xiiStringView sPath)
{
  if (sPath.IsEmpty())
    return XII_FAILURE;

  xiiFileReader file;

  XII_SUCCEED_OR_RETURN(file.Open(sPath));

  return ParseDocument(file);
}

Avoid:

xiiResult ProcessDocument(xiiStringView sPath)
{
  if (!sPath.IsEmpty())
  {
    xiiFileReader file;

    if (file.Open(sPath).Succeeded())
    {
      return ParseDocument(file);
    }
  }

  return XII_FAILURE;
}

The preferred implementation expresses the unsuccessful conditions first and leaves the primary operation at the function’s normal indentation level.

Cleanup and Early Returns

Early returns MUST NOT bypass required cleanup.

Where cleanup is necessary, prefer scoped ownership or another established resource-management mechanism rather than duplicating cleanup logic across failure branches.

A function with a single exit point may be preferable when a required finalization step cannot be represented safely through RAII.

Guiding principle:

Reject invalid states early and keep the successful path clear, but never simplify control flow at the expense of cleanup or invariants.

8.2 Use the Simplest Appropriate Branching Construct

Branching constructs SHOULD match the nature of the decision being expressed.

Do not introduce runtime polymorphism, template machinery, or complicated conditional expressions when ordinary control flow adequately expresses the requirement.

General Requirements

• Use if and else for general conditional logic.
• Use switch when selecting among discrete values, particularly enum states.
• Use if constexpr when compile-time conditions determine valid template implementations.
• Prefer ordinary compile-time constants over preprocessor conditionals when C++ language constructs are sufficient.
• Avoid long chains of runtime type checks when a genuine polymorphic interface would better represent the required behavior.
• Do not introduce inheritance or virtual dispatch solely to replace a small, stable conditional.
• Branches MUST preserve the same documented invariants regardless of the selected path.
• Exhaustive branching over enum values SHOULD make newly introduced values detectable through compiler diagnostics or review.

Discrete Alternatives

Prefer:

xiiResult ProcessTask(xiiTaskState::Enum state)
{
  switch (state)
  {
    case xiiTaskState::Pending:
      return QueueTask();

    case xiiTaskState::Running:
      return UpdateTask();

    case xiiTaskState::Completed:
      return FinalizeTask();
  }

  return XII_FAILURE;
}

When an enum is intended to be exhaustive, explicitly listing its supported values makes the contract easier to inspect.

A final failure return can handle invalid numeric representations without hiding missing cases behind a default branch.

Whether compiler warnings detect new enum values depends on the compiler and configured warning policy.

Default Cases

A default branch is appropriate when unknown values have a meaningful, documented fallback.

Prefer when unknown values are expected:

switch (message.m_Type)
{
  case xiiMessageType::Connect:
    HandleConnection();
    break;

  case xiiMessageType::Disconnect:
    HandleDisconnection();
    break;

  default:
    HandleUnknownMessage(message);
    break;
}

Do not use a silent default merely to suppress warnings when every known enum value requires explicit handling.

Compile-Time Branching

Use if constexpr when template logic depends on compile-time type properties.

template <typename T>
void ResetValue(T& value)
{
  if constexpr (std::is_trivially_copyable_v<T>)
  {
    value = T{};
  }
  else
  {
    value.Reset();
  }
}

This example assumes the supported non-trivially-copyable types provide Reset().

Compile-time branching MUST still establish a valid contract for every supported template instantiation.

Guiding principle:

Choose control flow according to the decision being made. Prefer explicit branches over unnecessary dispatch machinery.

8.3 Loops and Iteration

Iteration MUST preserve container invariants, element validity, and any ordering guarantees required by the operation.

Select the loop construct that most clearly communicates whether the operation depends on elements, indices, or iterator behavior.

General Requirements

• Prefer range-based loops when only element access is required.
• Use index-based loops when the index has semantic meaning or is necessary for the algorithm.
• Use explicit iterators when container mutation, traversal rules, or specialized iteration requires them.
• Do not repeatedly perform expensive computations in loop conditions when their results can be safely reused.
• Avoid unnecessary allocations, copies, and indirect access in demonstrated hot loops.
• Do not mutate a container during iteration unless the iteration pattern explicitly supports the mutation.
• Container removal MUST account for iterator, pointer, reference, and index invalidation.
• Do not assume that container removal preserves order unless the selected operation guarantees it.
• Loop termination MUST be well-defined, including for empty collections and boundary values.
• Avoid modifying the loop control variable unexpectedly inside the body.

Element-Based Iteration

Prefer:

for (const xiiResourceEntry& entry : m_Entries)
{
  ProcessEntry(entry);
}

Use mutable references only when modification is intended.

for (xiiResourceEntry& entry : m_Entries)
{
  entry.m_bActive = false;
}

Index-Based Iteration

Use indices when element positions are part of the operation’s meaning.

for (xiiUInt32 uiIndex = 0; uiIndex < m_Entries.GetCount(); ++uiIndex)
{
  UpdateEntry(uiIndex, m_Entries[uiIndex]);
}

Index types SHOULD be compatible with the container’s supported index range.

Avoid narrowing a container’s element count into a smaller integer type without establishing that the value fits.

Removal During Iteration

Removal operations may shift elements, replace removed elements with the last element, or invalidate iterators.

For example, when removal order is unimportant and RemoveAtAndSwap() provides the expected semantics:

for (xiiUInt32 uiIndex = 0; uiIndex < m_Entries.GetCount();)
{
  if (m_Entries[uiIndex].m_bExpired)
  {
    m_Entries.RemoveAtAndSwap(uiIndex);
    continue;
  }

  ++uiIndex;
}

The index is not advanced following removal because another element may have been moved into the current position.

Do not use swap-based removal when preserving the order of surviving elements is a documented requirement.

Loop Progress

Every potentially unbounded loop MUST have a defined progress or termination mechanism.

This is especially important for polling, task scheduling, synchronization, and resource reclamation.

Busy-wait loops SHOULD NOT be introduced when an appropriate blocking or event-driven mechanism is available.

Guiding principle:

Iterate according to the semantics of the data and the operation. Container mutation, ordering, and progress must remain explicit.

8.4 Comparators and Ordering Contracts

Comparators used by sorting and ordered containers MUST satisfy the ordering requirements of the relevant algorithm.

For standard strict-ordering algorithms, the comparator must establish a strict weak ordering over the supported input domain.

General Requirements

• Strict ordering comparators MUST return false when comparing equivalent values.
• Do not use <= or >= as strict ordering comparators.
• Comparators MUST produce consistent results for unchanged inputs.
• Comparator behavior MUST NOT depend on mutable state that can change during sorting.
• Avoid comparators with observable side effects.
• Do not modify compared elements from within the comparator.
• Sorting MUST NOT be assumed stable unless the algorithm explicitly guarantees stability.
• Tie-breaking behavior MUST be defined when equal primary keys require deterministic ordering.
• Comparators involving floating-point values MUST account for NaNs or establish a valid input domain that excludes them.

Prefer:

m_Entries.Sort([](const auto& a, const auto& b)
{
  return a.m_iPriority > b.m_iPriority;
});

This sorts entries by descending priority.

However, it does not guarantee the relative order of entries with equal priorities if the sorting algorithm is unstable.

Deterministic Tie-Breaking

When deterministic ordering among equal priorities is required, use an explicit secondary key.

m_Entries.Sort([](const auto& a, const auto& b)
{
  if (a.m_iPriority != b.m_iPriority)
    return a.m_iPriority > b.m_iPriority;

  return a.m_uiRegistrationOrder < b.m_uiRegistrationOrder;
});

The registration order must represent a stable and well-defined value for the relevant sorting operation.

Do not introduce artificial secondary keys unless deterministic tie ordering is a genuine requirement.

Invalid Comparators

Avoid:

m_Entries.Sort([](const auto& a, const auto& b)
{
  return a.m_iPriority >= b.m_iPriority;
});

For equal values, the comparator returns true in both directions.

This violates the strict ordering requirements and can result in undefined behavior when used with sorting algorithms that require strict weak ordering.

Floating-Point Ordering

Ordinary floating-point < does not establish strict weak ordering over a domain containing NaNs.

When sorting floating-point data that may contain NaNs, define an explicit ordering policy or reject invalid values before sorting.

Do not use approximate equality in a comparator without verifying that the resulting relation still satisfies the ordering requirements.

Guiding principle:

Ordering is an algorithmic contract. Comparators must be mathematically valid, deterministic for their supported inputs, and consistent with required tie semantics.

8.5 Boolean Logic and Conditional Expressions

Boolean expressions SHOULD make their intended meaning and evaluation order apparent.

Prefer straightforward predicates over compact expressions that require careful reconstruction of operator precedence.

General Requirements

• Use parentheses when mixing logical operators in expressions whose grouping may be misinterpreted.
• Prefer descriptive intermediate predicates for complex domain-specific conditions.
• Avoid unnecessary negations and double-negative state names.
• Do not introduce intermediate boolean variables for every trivial condition.
• Do not rely on implicit precedence when explicit grouping materially improves clarity.
• Avoid boolean expressions that combine unrelated side effects.
• Use short-circuit operators deliberately when later operands depend on earlier conditions.
• Conditional expressions MUST preserve the documented evaluation and failure semantics.

Prefer:

const bool bValidSession = session.IsActive() && session.GetSessionId() == uiExpectedSession;

const bool bHasDependencies = pScheduler != nullptr && pResourceManager != nullptr;

if (!bValidSession || !bHasDependencies)
  return XII_FAILURE;

This separates session validity from dependency availability.

Short-Circuit Evaluation

Logical && and || operators evaluate their operands with defined short-circuit behavior.

Prefer:

if (pResource != nullptr && pResource->IsReady())
{
  ProcessResource(*pResource);
}

The resource is accessed only when the pointer is non-null.

Do not replace logical operators with bitwise operators when short-circuit evaluation is required.

Avoid Redundant Predicates

Avoid:

if (bInitialized == true)
{
  Execute();
}

Prefer:

if (bInitialized)
{
  Execute();
}

For negative conditions:

if (!bInitialized)
  return XII_FAILURE;

Do not sacrifice readability merely to eliminate parentheses or intermediate variables.

Guiding principle:

Boolean logic should communicate domain meaning clearly while preserving correct precedence and short-circuit behavior.

8.6 Avoid Hidden Mutations and Evaluation-Order Dependencies

Expressions MUST NOT rely on undefined or unspecified evaluation behavior.

Side effects should be explicit, appropriately sequenced, and easy to inspect.

General Requirements

• Do not modify the same scalar object multiple times in an expression when the modifications are unsequenced.
• Avoid combining resource creation, validation, mutation, and consumption in unnecessarily complex expressions.
• Prefer separate statements when evaluation order affects correctness.
• Do not rely on compiler-specific operand evaluation behavior.
• Function arguments SHOULD NOT contain interdependent side effects whose order matters.
• Increment and decrement operations SHOULD be used where their effects are obvious.
• Do not use comma expressions to combine unrelated operations.
• Side effects MUST remain visible when failure handling or synchronization depends on their ordering.

Avoid:

ProcessValues(++uiIndex, uiIndex++);

The expression modifies the same variable through multiple arguments and obscures the intended sequencing.

Prefer:

++uiIndex;

const xiiUInt32 uiCurrentIndex = uiIndex;
++uiIndex;

ProcessValues(uiCurrentIndex, uiIndex);

The intended sequence is explicit.

Resource Creation and Validation

Prefer:

xiiResourceHandle hResource = CreateResource(descriptor);

if (hResource.IsInvalidated())
  return XII_FAILURE;

InitializeResource(hResource);

Avoid:

InitializeResource(CreateResource(descriptor));

The avoided form prevents the caller from inspecting creation failure before attempting initialization.

This separation is especially important when the second operation requires a valid handle.

Guiding principle:

Observable state changes should occur in an explicit, understandable sequence. Expression compactness must not conceal evaluation or failure behavior.

8.7 Integer Conversions and Arithmetic

Integer arithmetic MUST respect the range, signedness, and representation requirements of the values being manipulated.

Overflow and narrowing errors can lead to invalid allocations, incorrect indexing, corrupted resource descriptions, and undefined behavior.

General Requirements

• Use integer types whose widths and signedness match the domain’s required range.
• Check for overflow before calculations whose results control allocation sizes, offsets, strides, or buffer capacities.
• Do not assume that widening the destination prevents overflow if intermediate arithmetic occurs in a narrower type.
• Validate potentially negative signed values before converting them to unsigned types.
• Narrowing conversions MUST be intentional and range-checked when the source may exceed the destination range.
• Use explicit casts where they communicate intentional conversions.
• Avoid unnecessary casts that conceal incorrect type choices.
• Division and modulo operations MUST establish valid nonzero divisors.
• Signed arithmetic MUST NOT rely on overflow.
• Unsigned wraparound MUST be intentional and documented when its behavior is required.
• Integer comparisons SHOULD avoid unintended signed/unsigned conversions.
• Avoid arithmetic involving invalid sentinel values unless the sentinel has been checked.

Multiplication Overflow

Prefer:

if (uiStride == 0U)
  return XII_FAILURE;

if (uiElementCount > xiiMath::MaxValue<xiiUInt64>() / uiStride)
  return XII_FAILURE;

const xiiUInt64 uiByteCount = static_cast<xiiUInt64>(uiElementCount) * uiStride;

The example assumes that both operands are unsigned and that zero stride is invalid under the operation’s contract.

Checking before multiplication prevents the result from wrapping.

Intermediate Arithmetic

Avoid:

xiiUInt32 uiWidth  = descriptor.m_uiWidth;
xiiUInt32 uiHeight = descriptor.m_uiHeight;

xiiUInt64 uiPixelCount = uiWidth * uiHeight;

The multiplication may overflow at the 32-bit width before its result is assigned to a 64-bit variable.

Prefer:

const xiiUInt64 uiPixelCount = static_cast<xiiUInt64>(descriptor.m_uiWidth) * descriptor.m_uiHeight;

Widening an operand before multiplication causes the multiplication to occur in the wider type.

This is sufficient only when the resulting value is guaranteed to fit within that type. Otherwise, an overflow check is still required.

Narrowing Conversions

Prefer:

if (uiElementCount > xiiMath::MaxValue<xiiUInt32>())
  return XII_FAILURE;

const xiiUInt32 uiCount = static_cast<xiiUInt32>(uiElementCount);

Do not perform narrowing conversions merely to satisfy a function signature without confirming that the value fits.

Signed and Unsigned Values

Avoid:

xiiInt32 iOffset = GetOffset();

xiiUInt32 uiOffset = static_cast<xiiUInt32>(iOffset);

If iOffset is negative, conversion to an unsigned type produces an unintended large value.

Prefer:

const xiiInt32 iOffset = GetOffset();

if (iOffset < 0)
  return XII_FAILURE;

const xiiUInt32 uiOffset = static_cast<xiiUInt32>(iOffset);

Division and Modulo

Prefer:

if (uiBucketCount == 0U)
  return XII_FAILURE;

const xiiUInt32 uiBucketIndex = uiHash % uiBucketCount;

Never assume a divisor is nonzero merely because normal execution typically supplies a valid value.

When nonzero is a programmer-facing precondition rather than recoverable input validation, enforce it according to §7.13.

Guiding principle:

Integer correctness requires control over widths, ranges, and conversions. Validate arithmetic before a result can overflow, narrow incorrectly, or violate an invariant.

8.8 Floating-Point Arithmetic and Comparisons

Floating-point calculations MUST account for finite precision, rounding behavior, and the possibility of special values.

Numerical code should use comparison and tolerance policies appropriate to the domain rather than assume that floating-point values behave like exact real numbers.

General Requirements

• Do not use exact equality for approximate numerical results unless exact representation or identity is part of the contract.
• Use tolerances appropriate to the scale, precision, and expected error of the operation.
• Avoid using a single universal epsilon for unrelated numerical domains.
• Consider absolute and relative tolerances when comparing values of different magnitudes.
• Handle NaNs and infinities when they may arise from external inputs or calculations.
• Do not assume floating-point expressions are associative.
• Avoid transformations that change numerical behavior unless their accuracy and performance implications are understood.
• Numerical algorithms SHOULD account for loss of precision, cancellation, and accumulation error where relevant.
• Do not rely on exact reproducibility across platforms unless the required compiler, instruction, and floating-point behavior is explicitly controlled.
• Floating-point values used in ordering, hashing, or identity comparisons MUST follow the requirements of those operations.

Approximate Equality

Avoid:

if (fCalculatedValue == fExpectedValue)
{
  AcceptResult();
}

Prefer when approximate equality is intended:

const float fDifference = xiiMath::Abs(fCalculatedValue - fExpectedValue);

const float fScale = xiiMath::Max(xiiMath::Abs(fCalculatedValue), xiiMath::Abs(fExpectedValue));

const float fTolerance = fAbsoluteTolerance + fRelativeTolerance * fScale;

if (fDifference <= fTolerance)
{
  AcceptResult();
}

This comparison combines absolute and relative tolerances.

It assumes the inputs and tolerance parameters satisfy the algorithm’s finite-value and nonnegative-tolerance requirements. Validate those assumptions where they are not guaranteed.

Exact Equality

Exact floating-point equality may be appropriate for:

• Comparing values that are required to match an exact representation.
• Checking values assigned from the same defined constant.
• Certain sentinel values where their meaning is explicitly defined.
• Algorithms whose mathematical contract requires bitwise or exact-value identity.

Do not replace every floating-point equality comparison with an epsilon check mechanically.

NaNs and Infinities

NaN values have unusual comparison semantics, including the fact that ordinary equality and ordering comparisons do not behave like comparisons over real numbers.

When finite values are required, validate them before performing calculations that depend on finite arithmetic.

if (!xiiMath::IsFinite(fDeltaTime))
  return XII_FAILURE;

This assumes the operation treats non-finite time values as invalid input.

Numerical Stability

Prefer numerically stable formulations when equivalent mathematical expressions exhibit different error behavior.

For iterative simulations, reductions, and long-running computations, consider how rounding error accumulates over time.

Reordering floating-point operations for performance MUST account for its effect on numerical accuracy and reproducibility.

Guiding principle:

Floating-point correctness is defined by acceptable numerical error and explicit domain assumptions, not by the appearance of mathematical equivalence.

8.9 Switch Fallthrough

Fallthrough between switch cases MUST be intentional and immediately recognizable.

Use the standard [[fallthrough]] attribute where supported and consistent with the surrounding code.

General Requirements

• Implicit fallthrough MUST NOT occur accidentally.
• Intentional fallthrough SHOULD use [[fallthrough]].
• Do not rely solely on comments to indicate fallthrough when the compiler supports the standard attribute.
• Each case SHOULD terminate through break, return, another control transfer, or explicit fallthrough.
• Avoid fallthrough when duplicating a small amount of straightforward code would communicate the behavior more clearly.
• Multiple case labels sharing the same body do not require [[fallthrough]] between consecutive labels.
• Fallthrough MUST NOT bypass required initialization or violate variable scope rules.

Prefer:

switch (state)
{
  case xiiTaskState::Failed:
    LogTaskFailure();
    [[fallthrough]];

  case xiiTaskState::Cancelled:
    ReleaseTaskResources();
    break;

  case xiiTaskState::Completed:
    FinalizeTask();
    break;
}

The failure case performs additional logging before intentionally sharing cleanup behavior with cancellation.

Shared Case Bodies

When multiple values require identical behavior, group their labels.

switch (state)
{
  case xiiTaskState::Failed:
  case xiiTaskState::Cancelled:
    ReleaseTaskResources();
    break;

  case xiiTaskState::Completed:
    FinalizeTask();
    break;
}

This is not an implicit fallthrough error; both labels intentionally select the same statements.

Guiding principle:

Switch cases should have explicit termination behavior. Intentional fallthrough must be visible to both readers and compiler diagnostics.

8.10 Conditional Compilation and Feature Selection

Conditional compilation SHOULD be limited to cases where behavior genuinely differs by platform, compiler, build configuration, or compile-time feature availability.

Prefer ordinary C++ constructs when they provide equivalent functionality without introducing unnecessary preprocessor complexity.

General Requirements

• Use established XII feature and platform macros rather than inventing alternative detection mechanisms.
• Follow the repository’s conventions for XII_ENABLED and related compile-time feature checks.
• Do not use runtime checks for features that are intentionally unavailable in a given build configuration when compile-time exclusion is required.
• Do not use preprocessor conditionals when if constexpr or ordinary constant expressions provide a clearer solution.
• Platform-specific code SHOULD remain within the appropriate platform implementation rather than spread throughout portable modules.
• Conditional branches MUST preserve the documented interface contract across supported configurations.
• Avoid deeply nested preprocessor conditionals.
• Build configurations MUST NOT silently change public type layouts or exported interfaces when those interfaces require binary compatibility.

Example:

#if XII_ENABLED(XII_PLATFORM_WINDOWS)
  InitializeWindowsPlatform();
#elif XII_ENABLED(XII_PLATFORM_LINUX)
  InitializeLinuxPlatform();
#else
  InitializeGenericPlatform();
#endif

The exact feature macros and supported fallbacks must follow the existing repository definitions.

Compile-Time Versus Runtime Capabilities

Compile-time availability and runtime capability are separate concepts.

A feature may be compiled into the engine but remain unsupported by the active device or execution environment.

Use runtime capability queries when feature support depends on detected hardware, drivers, or system configuration.

Do not assume that compilation of a backend implies support for every optional feature.

Guiding principle:

Use conditional compilation to express build-time availability and runtime checks to express actual capabilities. Keep both mechanisms explicit and appropriately scoped.

8.11 Assertions and Unreachable States

Assertions SHOULD be used to detect violated internal invariants and programmer-facing preconditions.

They MUST NOT replace ordinary error handling for expected runtime failures.

General Requirements

• Assertions MUST express conditions expected to hold during every valid execution of the relevant code path.
• Do not rely on assertions to perform required initialization, mutation, or cleanup.
• Do not place essential side effects inside assertion expressions.
• Expected failures caused by external data or environmental conditions MUST be handled through the appropriate error mechanism.
• Unreachable-state assumptions MUST be justified by established invariants.
• Do not introduce compiler-specific unreachable hints when an invalid state can legitimately occur.
• Assertions SHOULD include diagnostics that identify the violated contract.
• Do not use assertions merely to suppress handling of a state that the public API permits.

Prefer:

XII_ASSERT_DEV(uiIndex < m_Entries.GetCount(), "Resource index is outside the valid range.");

ProcessEntry(m_Entries[uiIndex]);

This is appropriate when the caller is required by contract to supply a valid internal index.

For externally supplied indices, use explicit runtime validation instead.

Essential Side Effects

Avoid:

XII_ASSERT_DEV(InitializeResources().Succeeded(), "Initialization failed.");

If assertions are disabled, the initialization operation may not execute.

Prefer:

const xiiResult result = InitializeResources();

XII_ASSERT_DEV(result.Succeeded(), "Initialization failed.");

This version preserves execution of the operation regardless of whether the assertion is active.

If initialization failure is an expected runtime condition, the failure should instead be propagated or handled explicitly.

Guiding principle:

Assertions verify invariants; they must never be required for correct execution or substitute for recoverable error handling.

8.12 Expression Complexity and Readability

Expressions SHOULD remain understandable without requiring readers to reconstruct several independent operations or subtle language rules.

Prefer explicit intermediate values when they clarify units, ownership, ordering, or domain meaning.

General Requirements

• Avoid excessively nested conditional operators.
• Do not combine unrelated calculations and side effects into a single expression.
• Prefer named intermediate values when they clarify important assumptions or units.
• Avoid introducing intermediate values that merely duplicate obvious expressions.
• Use parentheses to make non-obvious precedence explicit.
• Prefer ordinary statements over complicated expression constructs when side effects or failure behavior are involved.
• Expression refactoring MUST preserve evaluation order and numerical behavior where those characteristics are part of the contract.
• Do not assume that algebraically equivalent expressions have identical integer-overflow or floating-point behavior.

Avoid:

const xiiUInt32 uiResult = bEnabled ? (bReady ? uiPrimary : uiFallback) : (bDefault ? uiDefault : 0U);

Prefer:

xiiUInt32 uiResult = 0U;

if (bEnabled)
{
  uiResult = bReady ? uiPrimary : uiFallback;
}
else if (bDefault)
{
  uiResult = uiDefault;
}

The second form makes each decision explicit.

A simple conditional expression remains appropriate when it selects between two straightforward values.

const xiiUInt32 uiCapacity = bUseLargeBuffer ? uiLargeCapacity : uiSmallCapacity;

Do not replace every conditional operator with a multi-line branch mechanically.

Guiding principle:

Expressions should make calculations and decisions easier to understand, not compress multiple responsibilities into fewer lines.

8.13 Determinism and Observable Ordering

Operations whose correctness depends on execution order MUST establish that order explicitly.

This applies to scheduling, event processing, serialization, reductions, resource transitions, and other systems where observable results depend on sequencing.

General Requirements

• Do not assume iteration order is deterministic unless the container explicitly guarantees it.
• Do not rely on hash-table iteration order for behavior requiring stable ordering.
• Sorting MUST establish the required tie-breaking semantics when equivalent keys have observable consequences.
• Concurrent execution MUST NOT be assumed deterministic without an explicit synchronization or scheduling contract.
• Side-effect ordering MUST remain well-defined when observable behavior depends on it.
• Serialization and persistent formats MUST use stable ordering where the format requires reproducible output.
• Do not introduce global ordering requirements when operations are independent and the additional synchronization would be unnecessary.
• Performance optimizations that reorder operations MUST preserve required observable semantics.

Container Ordering

Avoid when stable output is required:

for (const auto& entry : m_ResourceMap)
{
  SerializeResource(entry);
}

A hash-based container may not provide a stable iteration order.

Where deterministic serialization is required, collect and order the relevant entries according to a defined key before serializing them.

Parallel Execution

Concurrent operations may complete in different orders across executions.

When completion order affects externally visible state, the implementation must either enforce a deterministic order or explicitly document that ordering is not guaranteed.

Do not impose determinism on unrelated independent operations unless it is a genuine system requirement.

Guiding principle:

Ordering must be intentional. When behavior depends on sequence, establish that sequence through documented contracts rather than incidental container or scheduling behavior.

9. Modern C++23 Features

XII targets C++23 and should take advantage of modern language facilities when they improve correctness, expressiveness, maintainability, or measurable performance.

Modern C++ features MUST be adopted deliberately. Language availability alone does not justify introducing a feature when an existing engine abstraction or simpler construct already expresses the intended behavior.

The requirements in this section complement §1.1 (Correctness), §1.5 (Performance), §5 (Type Design), §6 (Ownership and Lifetime), and §7 (Function Interfaces).

9.1 Use Modern C++ When It Improves Clarity

C++23 is XII’s language baseline, but the availability of a feature in the language standard does not guarantee complete support across all compilers, standard libraries, or target platforms.

General Requirements

• Modern C++ features SHOULD be preferred when they provide clearer semantics, stronger compile-time guarantees, or simpler implementations.
• Features MUST be supported by the minimum compiler and standard-library versions required by XII.
• Do not introduce language features merely because they are newer than an existing implementation.
• Prefer standard language facilities over custom implementations when the standard facility meets the engine’s requirements without introducing incompatible dependencies.
• Existing XII abstractions SHOULD remain authoritative where they provide engine-specific allocation, reflection, serialization, or platform behavior.
• Do not introduce new generic wrappers around standard language features without a demonstrated requirement.
• Avoid depending on compiler extensions in portable engine code unless those extensions are isolated behind established platform abstractions.
• Changes to compiler or standard-library requirements MUST consider every supported platform and build configuration.
• Modernization MUST NOT alter observable behavior, ownership semantics, or binary compatibility unintentionally.

Feature Availability

Before introducing a less commonly used C++23 feature, consider:

1. Whether every supported compiler accepts the required syntax.
2. Whether the required standard-library implementation is available.
3. Whether the feature interacts correctly with XII’s build configurations.
4. Whether it introduces additional dependencies or binary compatibility concerns.
5. Whether the resulting implementation is clearer than the existing alternative.

Feature-test macros SHOULD be used when conditional support is necessary and consistent with the repository’s platform configuration system.

Guiding principle:

Modern C++ should simplify engineering, not complicate it. Prefer language features that strengthen contracts and reduce unnecessary implementation complexity.

9.2 Type Deduction with auto

Use auto when type deduction improves readability without concealing important semantic information.

Explicit types remain valuable when they communicate precision, ownership, resource identity, or conversion behavior.

General Requirements

• Use auto when the type is immediately apparent from the initializer.
• Prefer explicit types when the type communicates meaningful domain semantics.
• Use auto for iterators, verbose template instantiations, and generic code where spelling the complete type adds little value.
• Do not use auto merely to avoid understanding the type returned by an operation.
• Avoid deduced types when unintended signedness, precision, copying, or reference removal could affect correctness.
• Use auto& and const auto& when reference semantics are intended.
• Avoid unintended copies caused by plain auto when the initializer produces a reference.
• Public interfaces SHOULD expose concrete return types when those types form part of the documented contract.
• Do not use abbreviated function templates accidentally when a non-template interface is intended.

Prefer when the type communicates meaning:

const xiiUInt64 uiSimulationStep = simulation.GetStepCount();

xiiUniquePtr<xiiSimulationData> pData = CreateSimulationData();

Prefer when the initializer makes the type obvious:

auto pData = XII_DEFAULT_NEW(xiiSimulationData);

auto it = m_Resources.GetIterator();

Reference Preservation

Plain auto generally deduces a value type rather than preserving the reference category of the initializer.

Avoid when mutation of the original is intended:

auto entry = m_Entries[uiIndex];

entry.m_bActive = false;