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/ 22 - start every source-file with a header comment
23 - use outline headings to organize your program
24 - use ulang-comments as needed for referencing bugs, notes, etc.
25 - inline documentation should be declarative. your code explains your
27 - variables, imports, and exports belong at the top of a file
28 - =main= functions belong at the bottom of a file
29 - use LSP wherever possible (eglot, slime)
31 - prefer symbol docs to comments
32 - use stdin/stdout/stderr correctly - see
[[https://zenodo.org/records/3414191][CDR-11]] 33 - always prefer
=core= libraries over vendored dependencies
34 - use the compiler built-ins - if a function or class is generally
35 useful, add it to the core
36 - use conditions, restarts, and error handling where appropriate
37 - save type declarations and hairy optimizations for when the API is
39 - don't be afraid of macros
41 - define systems using keyword symbols
42 - use slash instead of dash for path separation in system names:
=:foo/bar= 43 - define your test system in the same file with a name of:
=:foo/tests= 44 - where possible, avoid collisions with systems in Quicklisp
46 - declare packages in a file named
=pkg.lisp= 47 - when multiple packages are being declared, consider a wrapper
49 - declare with
~UIOP:DEFINE-PACKAGE~ and
~:USE-REEXPORT~ 50 - package names are either the same as their system name or have the
51 system name as their root path.
52 - use
~:NICKNAMES~ to declare alternative names for your package
54 - prefer
=:default-initargs= over
=:initform=.
56 - always prefer
=core= libraries to vendored dependencies
57 - don't make
=mod.rs= files
58 - use the
=foo.rs=,
=foo/*= pattern instead
59 - derive
=Debug= and
=Clone= always
60 - write a sensible
=Display= impl
61 - derive default methods for
=Default=,
=Hash=,
=Copy=, etc where possible
62 - use generics where appropriate:
=foo<P:AsRef<Path>>(path:P){p.as_ref();}=