STYLE 3.2 KiB raw
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
* Use receiver methods for operations on an existing custom type.
22
  Use module functions for constructors and conversions without a receiver.
23
24
CONSTANTS
25
26
* Use named constants for numbers that encode hardware or protocol values,
27
  representation limits, or resource policies when a name makes their purpose
28
  clear. Keep constants near related constants and reuse existing definitions.
29
* Keep literals when their meaning is clear, such as zero, one, simple
30
  arithmetic, and independent test inputs or expected bytes.
31
32
NAMES
33
34
* Name fields after their role in the abstraction, not after an incidental implementation detail.
35
* Name callbacks after what the caller is asking them to do.
36
* When wrapping a lower-level operation, choose a name that distinguishes the wrapper from the operation it delegates to.
37
* Keep function names short, but not at the cost of hiding important context.
38
39
WHITESPACE
40
41
* Don't inline blocks like `if x { return true; }`, always return after `{`.
42
* Don't add a blank line after a closing `}` inside a function.
43
44
HELPERS
45
46
* Do not create small helper functions when they are only used in one place.
47
* Generally avoid one-line helpers, unless it's a complicated line.
48
49
DOCUMENTATION
50
51
* Start modules with `//!` documentation that states the module's role.
52
* Document all top-level types, functions, constants, and record/union fields with `///`.
53
* Document constants by explaining the architectural or representation limit they encode.
54
* Never write documentation that refers to the current context in which the code is written.
55
56
RE-USE
57
58
* Always look for functions in the standard library that you can re-use, instead of implementing your own.
59
60
UNIONS & OPTIONS
61
62
* When mutable state is stored inside a union payload, write updated payload values back to the owning union.
63
* Use `let-else` and `if let` to unwrap optionals or match variants at the point where failure is handled.
64
65
ERRORS
66
67
* Use `panic` for impossible internal invariants and `throw` for recoverable or user-facing failures.
68
* Panic strings should be prefixed by the enclosing function name, and ":".
69
* Use `assert` instead of `panic` when it's clearer/simpler.
70
71
MODULES
72
73
* Keep imports and sub-modules at the top, then constants, then types, then functions.
74
75
TESTS
76
77
* In tests, use `assert` for expected behavior and keep distinct scenarios in small helper functions when covering multiple cases.
78
79
FORMATTING
80
81
* Don't add blank lines after closing braces (`}`).
82
* Group `let`/`let mut` statements together when possible.
83
* Wrap lines at 80 columns.
84
* Avoid inline blocks, eg. DO NOT do `if n { return true; }`.
85
* Always follow semicolons (`;`) with a new line.