radiance · Radiance self-hosting compiler

compiler/ lib/ scripts/ seed/ sublime/ test/ vim/ .gitignore 366 B .gitsigners 112 B LICENSE 1.1 KiB Makefile 3.6 KiB README 2.5 KiB STYLE 2.5 KiB std.lib 1.2 KiB std.lib.test 347 B

STYLE 2.5 KiB raw

=====
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.

1	=====
2	STYLE
3	=====
4
5	Coding style guide for the Radiance language.
6
7	BOOLEANS
8
9	* Use small unions for mode, role, and state choices instead of bare booleans.
10
11	CALLSITES
12
13	* Avoid boolean parameters when the meaning is not obvious at the callsite.
14	* Use option records when a function takes multiple configuration values, when that helps with clarity.
15	* Keep callsites readable without needing to inspect the callee signature.
16
17	TYPES
18
19	* Prefer one union that encodes valid state over several fields that can drift out of sync.
20	* Do not store fields that are only meaningful in one mode unless the mode is encoded in the type.
21
22	NAMES
23
24	* Name fields after their role in the abstraction, not after an incidental implementation detail.
25	* Name callbacks after what the caller is asking them to do.
26	* When wrapping a lower-level operation, choose a name that distinguishes the wrapper from the operation it delegates to.
27	* Keep function names short, but not at the cost of hiding important context.
28
29	HELPERS
30
31	* Do not create small helper functions when they are only used in one place.
32	* Generally avoid one-line helpers, unless it's a complicated line.
33
34	DOCUMENTATION
35
36	* Start modules with `//!` documentation that states the module's role.
37	* Document all top-level types, functions, constants, and record/union fields with `///`.
38	* Replace magic numbers with named constants near related constants.
39	* Document constants by explaining the architectural or representation limit they encode.
40	* Never write documentation that refers to the current context in which the code is written.
41
42	RE-USE
43
44	* Always look for functions in the standard library that you can re-use, instead of implementing your own.
45
46	UNIONS & OPTIONS
47
48	* When mutable state is stored inside a union payload, write updated payload values back to the owning union.
49	* Use `let-else` and `if let` to unwrap optionals or match variants at the point where failure is handled.
50
51	ERRORS
52
53	* Use `panic` for impossible internal invariants and `throw` for recoverable or user-facing failures.
54	* Panic strings should be prefixed by the enclosing function name, and ":".
55	* Use `assert` instead of `panic` when it's clearer/simpler.
56
57	MODULES
58
59	* For large modules, group related declarations with simple ASCII section banners such as `// Constants //` or `// Error Handling //`.
60	* Keep imports and sub-modules at the top, then constants, then types, then functions.
61
62	TESTS
63
64	* In tests, use `assert` for expected behavior and keep distinct scenarios in small helper functions when covering multiple cases.