Chapter 3 Language, Conventions, and CNAEXT

CNA’s porting rules name a single authoritative behavioral reference: a local FNA source tree. The instruction is blunt: “Do not treat old CNA code or AI-generated stubs as authoritative if they conflict with the FNA reference API.” Concretely, this means:

• •

  Class names, struct names, enum names, method names, operator names, and constant names must match XNA/FNA exactly. A method is not renamed to be “more C++-like” if that would diverge from the reference.

• •

  Behavior is matched over personal preference: packed value layouts (Color stores its channels as AABBGGRR), clamping behavior, integer cast behavior, operator behavior, method overloads, default values, and exception behavior where practical, all follow FNA even when a different choice would look cleaner in isolation.

• •

  C++ member declaration order mirrors the original C# source order where practical, specifically to keep diff-based review tractable against the reference.

This is the single idea that makes the rest of the house style legible: every convention below exists to answer the same question — how do you represent a C# concept in C++ without losing the ability to diff against the original?

CNA code lives in exactly one of two namespace families, and the rule for which one is absolute:

Original XNA types are never moved into the CNA namespace, and the reverse is equally firm: anything that is not part of the real XNA 4.0 API must not silently live inside Microsoft::Xna::Framework unmarked. That is what the CNAEXT marker exists for.

CNAEXT is an empty marker macro, defined in modules/core/include/CNA/CNAHelper.hpp, whose only job is to visibly tag a declaration inside the XNA namespace tree as not part of the original XNA 4.0 API — a rumble-and-gyro extension on GamePad, a GetTypeName() override, a raw joystick API, a haptics subsystem. Two concrete examples from the real codebase:

What makes this more than a documentation convention is a compiler-enforced check described in Chapter 1, precisely: CNAHelper.hpp’s own definition of CNAEXT is conditional on a second, distinct macro, CNA_STRICT_XNA_API — in a normal build CNAEXT expands to nothing at all (it is documentation only); only when CNA_STRICT_XNA_API is defined does it expand to [[deprecated("CNAEXT: not part of the XNA 4.0 API surface")]]. That define is never set for the normal CNA library target — it is scoped to exactly two small standalone CMake targets in cmake/Harnesses.cmake, each compiled with -Werror=deprecated-declarations on top of it, so a stray CNAEXT-tagged call anywhere those targets’ translation units can see turns into a hard build failure rather than a warning that could be scrolled past.

C# auto-properties (public byte R { get; set; }) become a fixed pair of C++ methods, never a public field, unless the surrounding type has already established a field-style convention:

Not every property setter is a bare field write, and the convention does not ask one to pretend otherwise: a C# property with real validation logic in its setter keeps that logic, translated directly, rather than being flattened into a public field for convenience. SkinnedEffect::WeightsPerVertex (Chapter 15) is a real instance of this, read directly from SkinnedEffect.cpp:

Two things this one setter does at once, both faithfully carried over from what a validated C# property would do: it rejects an invalid value outright (a real XNA/FNA SkinnedEffect genuinely only supports 1, 2, or 4 bone weights per vertex — there is no silent clamping to the nearest valid value), and it marks a dirty-shader-selection flag as a side effect of the assignment, since a changed weight count means a different GPU shader variant must be selected on the next Apply(). Neither behavior would survive a mechanical “just make it a public field” translation.

Wherever C# source uses a .NET primitive type name, CNA code uses the corresponding sharp-runtime alias rather than a raw C++ fundamental type, specifically so that the XNA-facing surface keeps a visible, greppable link back to its .NET origin:

If a needed alias does not yet exist, the rule is to add a minimal stub to sharp-runtime first — never to reach for a raw C++ type directly in the XNA API surface as a shortcut. This is the same missing-dependency discipline covered in §3.12 below.

C# events and delegates are modeled uniformly through sharp-runtime’s System::EventHandler<T>, never through an ad-hoc project-specific callback type:

C# interface relationships become C++ abstract base classes — for example Color implementing IEquatable<Color> and IPackedVector in C# becomes struct Color : public Graphics::PackedVector::IPackedVectorT<UInt32> in CNA. Where an exact mapping is not practical, the rule is to implement equivalent behavior and document the intentional deviation in the pull request description — explicitly not as a source comment, keeping the deviation visible to reviewers without cluttering the header for every future reader.

IDisposable follows a fixed pattern backed by sharp-runtime’s System::IDisposable:

with an isDisposed_ guard checked before any operation, throwing std::runtime_error on use-after-dispose.

C# internal members do not automatically become C++ public just because C++ lacks an internal keyword — they become private, protected, live in a detail/internal namespace, or are omitted from the port entirely. The house style calls out a concrete anti-example: a C# internal DebugDisplayString helper should not become a public C++ API method just because it was easy to leave public.

Each physical module owns its declarations under modules/<owner>/include/ and its implementation under modules/<owner>/src/. The public include subtree mirrors the namespace, while implementation paths may use a shorter subsystem directory:

Non-template implementations do not live in headers. At the pin, that subtree contains 125 .hpp files: 107 directly in the Microsoft::Xna::Framework::Graphics directory and 18 in its PackedVector child. The directory mirrors both namespace levels; calling all 125 files the flat “Graphics namespace” would erase that real nested boundary.

If correcting an API breaks an old demo, the demo is fixed — CNA does not carry a convenience alias just to keep outdated call sites compiling. The house style gives its own canonical wrong/right pair:

Every public method, constructor, property accessor, operator, and constant in every .hpp file must carry a Doxygen block — bare /// line comments are never acceptable on a public declaration (they remain acceptable only for brief inline notes inside a method body). The intent of the original C# XML doc comments (<summary>, <param>, <returns>) is preserved, often verbatim from FNA where the wording already fits, but never marked with a comment like “taken from FNA” — provenance belongs in the porting record, not scattered through the header.

When a file being ported references a type that does not exist yet, the rule is layered: if the missing type belongs to the .NET runtime (System.* or a primitive alias), it is added to sharp-runtime first, following the same minimal-stub discipline described in Chapter 2. Otherwise, a minimal, correctly named stub is added directly in CNA, in the correct final namespace, sufficient only to compile — never a large unrelated system built just to satisfy one missing dependency. Every stub introduced this way is reported in the task or PR description, so it is never silently forgotten as “real” once the build goes green.

CHECKLIST.md governs the full requirements for porting one FNA source file to CNA; the house rules single out its non-negotiable minimum:

• •

  An SPDX MS-PL license identifier at the top of both the .hpp and the .cpp.

• •

  #include "CNA/CNAHelper.hpp" in the header, whenever CNAEXT is used anywhere in that file.

• •

  Every method body checked line-by-line against the FNA equivalent, with every intentional deviation documented in a source comment (not silently absorbed).

• •

  Every concrete class inheriting System::Object overrides GetTypeName(), tagged CNAEXT, returning the fully-qualified .NET name (e.g. "Microsoft.Xna.Framework.Game").

• •

  A unit test for every public method, operator, and constant — with out-ref overloads tested separately from their value-returning counterparts, and static factory methods (CreateFromPoints, CreateMerged, CreateFromSphere, …) each getting a dedicated test.

A file is “done in one pass” — the house style explicitly rejects a “make-and-forget-partially” workflow where checklist items are deferred to a later, unscheduled pass.

None of the conventions above are unique or clever in isolation — type-alias tables and Doxygen mandates exist in a thousand C++ style guides. What is unusual is how tightly they are all in service of one measurable goal: keeping a large, multi-renderer, multi-platform C++ codebase auditable against a real external reference (FNA, real XNA 4.0, xna4-spec) at every layer — namespace, visibility, member order, type alias, and a compiler flag that turns “did we leak a non-XNA type into the XNA surface” into a build error instead of a hoped-for code-review catch. The rest of this book takes these conventions as read; when a later chapter says a class “matches FNA exactly,” this is the mechanism that claim rests on.