1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
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.
|
