diff options
Diffstat (limited to 'documentation/STYLE')
| -rw-r--r-- | documentation/STYLE | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/documentation/STYLE b/documentation/STYLE new file mode 100644 index 0000000..989b2b1 --- /dev/null +++ b/documentation/STYLE @@ -0,0 +1,58 @@ +When contributing to Sideros, you should take account of this +style guide, which is mostly based on the Zig documentation +style guide (https://ziglang.org/documentation/0.14.0/#Style-Guide). + +1. Avoid these words in type names: + - Value + - Data + - Context + - Manager + - utils, misc, or somebody's initials + +Everything is a value, all types are data, everything is context, all logic manages +state. Nothing is communicated by using a word that applies to all types. +Temptation to use "utilities", "miscellaneous", or somebody's initials is a failure +to categorize, or more commonly, overcategorization. Such declarations can live at the +root of a module that needs them with no namespace needed. + +2. Avoid Redundant Names in Fully-Qualified Namespaces +Every declaration is assigned a fully qualified namespace by the compiler, creating a +tree structure. Choose names based on the fully-qualified namespace, and avoid redundant +name segments. For example, let's say you're writing a wrapping interface over WASM and +you need to create a structure to hold WebAssembly values. If you are importing that +file using `@import`, you will assign the code to a namespace, for example `wasm`. +For this reason, you should avoid calling your WASM value interface something like +`WasmValue`, because it will end up being used as `wasm.WasmValue`, just call it `Value` +and the code will be overall more readable (`wasm.Value`). + +3. Whitespaces + - 4 spaces for indentation + - Open braces on same line, unless you need to wrap + - If a list of things is longer than 2, put each item + on its own row and excercise the ability to put an + extra comma at the end. + - Aim for 100 as line length. + +4. Names + - for types, use "TitleCase", unless it's a namespace, + in that case use "snake_case". + - if x is callable, and returns a `type`, then use "TitleCase" + - if x is callable, and doesn't return a `type`, use "camelCase" + - everything else should be "snake_case" +Generally speaking, try to name things using easily understandable identifiers. +This can mostly be done by just writing names as full english words, and avoiding +acronyms and similar things. For example, prefer `time` over `t`, `speed` over `spd` +and so on. Just by doing this most of the code wouldn't need comments, because the +code will describe the logic by itself. + +5. Comments +Comments should never explain how code works, but rather how code should be used. +As stated in part 4, Zig has an explicit syntax allowing to write readable code, +just by using extended words for names and thus, in-code comments, explaining +how a specific part of code works, can be completely avoided. +Documentation comments, instead, can be very useful when exposing types and +functions, so that the behaviour of those can be easily read without going +to look directly at the source code. +The only exception is when the code logic can't be easily readable by +humans for optimization reasons (bitwise magic, for example) and so +in that case, in-code comments are allowed. |