0
|
1
|
#+title: The Compiler Company Styleguide |
|
2
|
#+author: Richard Westhaver |
|
3
|
#+email: ellis@rwest.io |
2
|
4
|
#+setupfile: ../clean.theme |
4
|
5
|
#+glossary_sources: glossary.org |
0
|
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 |
1
|
17
|
:PROPERTIES: |
|
18
|
:ID: 5cee979a-3732-45ed-87f5-cadf591cac42 |
|
19
|
:END: |
0
|
20
|
- indent-offset = 2 |
|
21
|
- max-line-width = 80 |
|
22
|
- page-length ~ 32 |
|
23
|
- module-length ~ 512 |
|
24
|
- file-size ~ 1024 |
|
25
|
|
|
26
|
- start every source-file with a header comment |
|
27
|
- use outline headings to organize your program |
|
28
|
- use ulang-comments as needed for referencing bugs, notes, etc. |
|
29
|
- inline documentation should be declarative. your code explains your |
|
30
|
comments for you. |
|
31
|
- variables, imports, and exports belong at the top of a file |
|
32
|
- =main= functions belong at the bottom of a file |
|
33
|
- use LSP wherever possible (eglot, slime) |
|
34
|
* Common Lisp |
1
|
35
|
:PROPERTIES: |
|
36
|
:ID: d4c25810-ce35-411e-a371-67ab7e814260 |
|
37
|
:END: |
0
|
38
|
- prefer symbol docs to comments |
|
39
|
- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]] |
|
40
|
- always prefer =core= libraries over vendored dependencies |
|
41
|
- use the compiler built-ins - if a function or class is generally |
|
42
|
useful, add it to the core |
|
43
|
- use conditions, restarts, and error handling where appropriate |
|
44
|
- save type declarations and hairy optimizations for when the API is |
|
45
|
polished |
|
46
|
- don't be afraid of macros |
|
47
|
** Systems |
1
|
48
|
:PROPERTIES: |
|
49
|
:ID: 2a323c4c-362c-429f-9849-587e2a7311f5 |
|
50
|
:END: |
0
|
51
|
- define systems using keyword symbols |
|
52
|
- use slash instead of dash for path separation in system names: =:foo/bar= |
|
53
|
- define your test system in the same file with a name of: =:foo/tests= |
|
54
|
- where possible, avoid collisions with systems in Quicklisp |
|
55
|
** Packages |
1
|
56
|
:PROPERTIES: |
|
57
|
:ID: f735b4b5-4818-408b-a244-e2fb506c7ded |
|
58
|
:END: |
0
|
59
|
- declare packages in a file named =pkg.lisp= |
|
60
|
- when multiple packages are being declared, consider a wrapper |
|
61
|
package |
|
62
|
- declare with ~UIOP:DEFINE-PACKAGE~ and ~:USE-REEXPORT~ |
|
63
|
- package names are either the same as their system name or have the |
|
64
|
system name as their root path. |
|
65
|
- use ~:NICKNAMES~ to declare alternative names for your package |
|
66
|
** CLOS |
1
|
67
|
:PROPERTIES: |
|
68
|
:ID: 5068e164-764a-4843-be8f-126754938ef9 |
|
69
|
:END: |
0
|
70
|
- prefer =:default-initargs= over =:initform=. |
|
71
|
* Rust |
1
|
72
|
:PROPERTIES: |
|
73
|
:ID: 8e414073-36b6-45d4-9a11-e6de8a0a65e9 |
|
74
|
:END: |
0
|
75
|
- always prefer =core= libraries to vendored dependencies |
|
76
|
- don't make =mod.rs= files |
|
77
|
- use the =foo.rs=, =foo/*= pattern instead |
|
78
|
- derive =Debug= and =Clone= always |
|
79
|
- write a sensible =Display= impl |
|
80
|
- derive default methods for =Default=, =Hash=, =Copy=, etc where possible |
|
81
|
- use generics where appropriate: =foo<P:AsRef<Path>>(path:P){p.as_ref();}= |
|
82
|
* Emacs Lisp |
1
|
83
|
:PROPERTIES: |
|
84
|
:ID: 8b17f8a3-74f2-44cd-a5ce-7df540e2544c |
|
85
|
:END: |
0
|
86
|
* Org-mode |
1
|
87
|
:PROPERTIES: |
|
88
|
:ID: ea4fa698-7a46-46d6-a7a0-5b497119edf2 |
|
89
|
:END: |
0
|
90
|
* Shell |
1
|
91
|
:PROPERTIES: |
|
92
|
:ID: 10904e36-e4ac-4841-b602-d4dc68a54c71 |
|
93
|
:END: |
0
|
94
|
* Python |
1
|
95
|
:PROPERTIES: |
|
96
|
:ID: 5b402ced-2329-4a16-b512-76859157a9d6 |
|
97
|
:END: |