code-style

name

code-style

description

Write C/C++ in the Xenolith/Stappler monorepo the way the codebase is written. Use BEFORE creating or editing sources in runtime/, stappler/, xenolith/, tests/ or utils/ — new file, new header, new class, new platform branch, new allocation. Covers .cpp SCU vs .cc subunits, license/include-guard/namespace layout, SP_PUBLIC and SPRT_API, naming (_member, handleXxx, Rc<T>::create), #if SPRT_WINDOWS platform guards, pool vs malloc ownership rules (AllocPool, sprt::__delete, new (pool) T), independent pools that move between threads (PoolRef, SharedRef<T>, PoolObject), threads and dispatch (Looper, Task, Handle), the scene graph (Node geometry, and using System/Component instead of subclassing Node), strings (StringView lifetime, mem_std vs mem_pool, CallbackStream, reader API), Unicode text (compareCodepoints vs compareFolded vs collate, case mapping strings not characters, IDN, and the rules for generated Unicode tables), error handling with no exceptions (Status, Result<T>, slog(), asserts), weakly-typed data (data::Value: the mem_std/mem_pool interfaces, setValue(value, key) order, the read-only Value::Null sentinel, JSON/CBOR round-tripping), windows and OS integration (Context::createWindow + WindowSceneInfo, ui::SubWindow popups/tooltips, WindowCapabilities, DialogRequest and the reveal/trash shell actions), forms (ui::FormSystem as the focus group, addFormField adapters, FormFieldSlots, deferred focus), and what .clang-format already enforces.

Xenolith/Stappler code style

Full articles live in docs/usage/codestyle/, grouped by what you are touching — sources/, platform/, core/, scene/, ui/, window/, plus the standalone deferred-computation.adoc. This card holds the rules that are cheap to keep in context, and routes to the article when you need the detail. Read the article before writing a new file or touching an unfamiliar layer; the rules below are enough for an ordinary edit.

The design principle

Computation that can be deferred, must be deferred. If a result is not needed now, record that it is stale and compute it once where it is actually read — that collapses N mutations into one recomputation, elides work nobody reads, and runs with complete inputs. It is why the engine has dirty flags + phases instead of work in setters, lazy caches (_transformCacheDirty), sort-before-draw, per-field style accessors, Callback<void(StringView)> instead of returned strings, and demand-driven dispatch (subtree listener counters, frame stack). Don't defer when the bookkeeping costs more than the work, when it muddies lifetime, or for error detection. Details and examples: deferred-computation.adoc.

Golden rules

1. .cpp/.c are compile units (SCU); .cc files are #include-only subunits. A new .cc is not built until some .cpp includes it. Never compile a .cc standalone to "check" it — build its parent .cpp.

2. Every file starts with the MIT license block (/** … **/), copied from a neighbouring file (the copyright holder differs per subtree).

3. Include guard = repo-relative path, uppercased, trailing _ — XENOLITH_RENDERER_UI_ATOMS_XLUIBUTTON_H_. No #pragma once. Repeat the guard in the #endif comment.

4. Namespaces: namespace STAPPLER_VERSIONIZED stappler::… for stappler/xenolith, plain namespace sprt for runtime. Never write namespace stappler::… without the macro.

5. Exported entities get SP_PUBLIC (stappler/xenolith) or SPRT_API / SPRT_GLOBAL (runtime).

6. Includes are never auto-sorted (SortIncludes: Never) and order matters in an SCU. Append; don't reorganize. Use // IWYU pragma: keep for umbrella headers that look unused.

7. Naming: types and enumerators PascalCase; functions/locals camelCase; members _camelCase; file statics s_camelCase; macros SCREAMING_SNAKE with an SP_/SPRT_/XL_ prefix (__SPRT_* is internal — read only). Files: SP* in stappler, XL* in xenolith, lowercase in runtime/include/sprt, aggregators *.scu.cpp.

8. Virtual notification hooks are handleXxx(), never onXxx() (handleEnter, handleContentSizeDirty, handleLayoutChildren).

Where to read more

Task	Article
Designing a subsystem, an API or a data structure; deciding what to compute when	deferred-computation.adoc
Adding a source file; .cpp vs .cc; compile-checking one file	units-and-files.adoc
New header: license, guard, namespace, visibility macro, include order	file-layout.adoc
Naming a file, type, member, handler; the init()/create() pattern	naming.adoc
Platform/arch #if, per-platform values, how to verify guarded code	platform-guards.adoc
Rc/Ref, pools vs malloc, AllocPool, __delete, pool traps; independent pools (PoolRef, SharedRef<T>) that travel between threads	memory-and-ownership.adoc
What the formatter enforces and what it deliberately leaves alone	formatting.adoc
Passing/building/parsing text, StringView lifetime, pool vs malloc strings, unicode	strings.adoc
Comparing or sorting text, case mapping, domain names, touching a generated Unicode table	unicode-and-text.adoc
A function that can fail; Status/Result<T>, logging, assertions

Adjacent skills: xenolith-build (how to build/verify), css-engine (CSS subset rules for .css/pug), gui-debug, wine-debug, wasm-test.