9
|
1
|
{{{header(style, |
|
2
|
Richard Westhaver, |
|
3
|
ellis@rwest.io, |
|
4
|
The Compiler Company Styleguide)}}} |
|
5
|
|
|
6
|
As an organization we maintain a styleguide[fn:1] which lists all of |
|
7
|
the style guidelines we use for our code. If you are contributing to |
|
8
|
one of our projects, you should review and understand the relevant |
|
9
|
sections below. |
|
10
|
|
|
11
|
You should also review the [[file:ulang.org][ulang]] document, which may shine some light |
|
12
|
on code comments and developer docs. |
|
13
|
|
|
14
|
[fn:1] https://google.github.io/styleguide/ |
|
15
|
|
|
16
|
* General Programming |
|
17
|
- indent-offset = 2 |
|
18
|
- max-line-width = 80 |
|
19
|
- page-length ~ 32 |
|
20
|
- module-length ~ 512 |
|
21
|
- file-size ~ 1024 |
|
22
|
|
|
23
|
- start every source-file with a header comment |
|
24
|
- use outline headings to organize your program |
|
25
|
- use ulang-comments as needed for referencing bugs, notes, etc. |
|
26
|
- inline documentation should be declarative. your code explains your |
|
27
|
comments for you. |
|
28
|
- variables, imports, and exports belong at the top of a file |
|
29
|
- =main= functions belong at the bottom of a file |
14
|
30
|
- use LSP wherever possible (eglot, slime) |
9
|
31
|
* Common Lisp |
|
32
|
- prefer symbol docs to comments |
|
33
|
- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]] |
|
34
|
- always prefer =core= libraries over vendored dependencies |
14
|
35
|
- use the compiler built-ins - if a function or class is generally |
9
|
36
|
useful, add it to the core |
14
|
37
|
- use conditions, restarts, and error handling where appropriate |
|
38
|
- save type declarations and hairy optimizations for when the API is |
|
39
|
polished |
|
40
|
- don't be afraid of macros |
9
|
41
|
* Rust |
|
42
|
- don't make =mod.rs= files |
|
43
|
- use the =foo.rs=, =foo/*= pattern instead |
14
|
44
|
- derive =Debug= and =Clone= wherever possible |
|
45
|
- write a sensible =Display= impl |
|
46
|
- use generics where appropriate: =foo<P:AsRef<Path>>(path:P){p.as_ref();}= |
9
|
47
|
* Emacs Lisp |
|
48
|
* Org-mode |
|
49
|
* Shell |
|
50
|
* Python |