1 #+title: The Compiler Company Styleguide
2 #+author: Richard Westhaver
3 #+email: ellis@rwest.io
4 #+setupfile: ../../clean.theme
5 As an organization we maintain a styleguide
[fn:1] which lists all of
6 the style guidelines we use for our code. If you are contributing to
7 one of our projects, you should review and understand the relevant
10 You should also review the
[[file:ulang.org][ulang]] document, which may shine some light
11 on code comments and developer docs.
13 [fn:1] https:
//google.github.io/styleguide/ 17 :ID: 5cee979a-3732-45ed-87f5-cadf591cac42 25 - start every source-file with a header comment
26 - use outline headings to organize your program
27 - use ulang-comments as needed for referencing bugs, notes, etc.
28 - inline documentation should be declarative. your code explains your
30 - variables, imports, and exports belong at the top of a file
31 - =main= functions belong at the bottom of a file
32 - use LSP wherever possible (eglot, slime)
35 :ID: d4c25810-ce35-411e-a371-67ab7e814260 37 - prefer symbol docs to comments
38 - use stdin/stdout/stderr correctly - see
[[https://zenodo.org/records/3414191][CDR-11]] 39 - always prefer
=core= libraries over vendored dependencies
40 - use the compiler built-ins - if a function or class is generally
41 useful, add it to the core
42 - use conditions, restarts, and error handling where appropriate
43 - save type declarations and hairy optimizations for when the API is
45 - don't be afraid of macros
48 :ID: 2a323c4c-362c-429f-9849-587e2a7311f5 50 - define systems using keyword symbols
51 - use slash instead of dash for path separation in system names:
=:foo/bar= 52 - define your test system in the same file with a name of:
=:foo/tests= 53 - where possible, avoid collisions with systems in Quicklisp
56 :ID: f735b4b5-4818-408b-a244-e2fb506c7ded 58 - declare packages in a file named
=pkg.lisp= 59 - when multiple packages are being declared, consider a wrapper
61 - declare with
~UIOP:DEFINE-PACKAGE~ and
~:USE-REEXPORT~ 62 - package names are either the same as their system name or have the
63 system name as their root path.
64 - use
~:NICKNAMES~ to declare alternative names for your package
67 :ID: 5068e164-764a-4843-be8f-126754938ef9 69 - prefer
=:default-initargs= over
=:initform=.
72 :ID: 8e414073-36b6-45d4-9a11-e6de8a0a65e9 74 - always prefer
=core= libraries to vendored dependencies
75 - don't make
=mod.rs= files
76 - use the
=foo.rs=,
=foo/*= pattern instead
77 - derive
=Debug= and
=Clone= always
78 - write a sensible
=Display= impl
79 - derive default methods for
=Default=,
=Hash=,
=Copy=, etc where possible
80 - use generics where appropriate:
=foo<P:AsRef<Path>>(path:P){p.as_ref();}= 83 :ID: 8b17f8a3-74f2-44cd-a5ce-7df540e2544c 87 :ID: ea4fa698-7a46-46d6-a7a0-5b497119edf2 91 :ID: 10904e36-e4ac-4841-b602-d4dc68a54c71 95 :ID: 5b402ced-2329-4a16-b512-76859157a9d6