1 #+title: The Compiler Company Styleguide
2 #+author: Richard Westhaver
3 #+email: ellis@rwest.io
4 #+glossary_sources: acronyms terms
5 #+setupfile: ../clean.theme
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
11 You should also review the
[[file:ulang.org][ulang]] document, which may shine some light
12 on code comments and developer docs.
14 [fn:1] https:
//google.github.io/styleguide/ 18 :ID: 5cee979a-3732-45ed-87f5-cadf591cac42 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
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)
36 :ID: d4c25810-ce35-411e-a371-67ab7e814260 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
46 - don't be afraid of macros
49 :ID: 2a323c4c-362c-429f-9849-587e2a7311f5 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
57 :ID: f735b4b5-4818-408b-a244-e2fb506c7ded 59 - declare packages in a file named
=pkg.lisp= 60 - when multiple packages are being declared, consider a wrapper
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
68 :ID: 5068e164-764a-4843-be8f-126754938ef9 70 - prefer
=:default-initargs= over
=:initform=.
73 :ID: 8e414073-36b6-45d4-9a11-e6de8a0a65e9 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();}= 84 :ID: 8b17f8a3-74f2-44cd-a5ce-7df540e2544c 88 :ID: ea4fa698-7a46-46d6-a7a0-5b497119edf2 92 :ID: 10904e36-e4ac-4841-b602-d4dc68a54c71 96 :ID: 5b402ced-2329-4a16-b512-76859157a9d6