=====
STYLE
=====

Coding style guide for the Radiance language.

BOOLEANS

* Use small unions for mode, role, and state choices instead of bare booleans.

CALLSITES

* Avoid boolean parameters when the meaning is not obvious at the callsite.
* Use option records when a function takes multiple configuration values, when that helps with clarity.
* Keep callsites readable without needing to inspect the callee signature.

TYPES

* Prefer one union that encodes valid state over several fields that can drift out of sync.
* Do not store fields that are only meaningful in one mode unless the mode is encoded in the type.

NAMES

* Name fields after their role in the abstraction, not after an incidental implementation detail.
* Name callbacks after what the caller is asking them to do.
* When wrapping a lower-level operation, choose a name that distinguishes the wrapper from the operation it delegates to.
* Keep function names short, but not at the cost of hiding important context.

HELPERS

* Do not create small helper functions when they are only used in one place.
* Generally avoid one-line helpers, unless it's a complicated line.

DOCUMENTATION

* Start modules with `//!` documentation that states the module's role.
* Document all top-level types, functions, constants, and record/union fields with `///`.
* Replace magic numbers with named constants near related constants.
* Document constants by explaining the architectural or representation limit they encode.
* Never write documentation that refers to the current context in which the code is written.

RE-USE

* Always look for functions in the standard library that you can re-use, instead of implementing your own.

UNIONS & OPTIONS

* When mutable state is stored inside a union payload, write updated payload values back to the owning union.
* Use `let-else` and `if let` to unwrap optionals or match variants at the point where failure is handled.

ERRORS

* Use `panic` for impossible internal invariants and `throw` for recoverable or user-facing failures.
* Panic strings should be prefixed by the enclosing function name, and ":".
* Use `assert` instead of `panic` when it's clearer/simpler.

MODULES

* For large modules, group related declarations with simple ASCII section banners such as `// Constants //` or `// Error Handling //`.
* Keep imports and sub-modules at the top, then constants, then types, then functions.

TESTS

* In tests, use `assert` for expected behavior and keep distinct scenarios in small helper functions when covering multiple cases.