4 The Compiler Company Styleguide)}}}
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/ 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
28 - variables, imports, and exports belong at the top of a file
29 - =main= functions belong at the bottom of a file
30 - use LSP wherever possible (eglot, slime)
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
35 - use the compiler built-ins - if a function or class is generally
36 useful, add it to the core
37 - use conditions, restarts, and error handling where appropriate
38 - save type declarations and hairy optimizations for when the API is
40 - don't be afraid of macros
42 - define systems using keyword symbols
43 - use slash instead of dash for path separation in system names:
=:foo/bar= 44 - define your test system in the same file with a name of:
=:foo/tests= 45 - where possible, avoid collisions with systems in Quicklisp
47 - declare packages in a file named
=pkg.lisp= 48 - when multiple packages are being declared, consider a wrapper
50 - declare with
~UIOP:DEFINE-PACKAGE~ and
~:USE-REEXPORT~ 51 - package names are either the same as their system name or have the
52 system name as their root path.
53 - use
~:NICKNAMES~ to declare alternative names for your package
55 - prefer
=:default-initargs= over
=:initform=.
57 - always prefer
=core= libraries to vendored dependencies
58 - don't make
=mod.rs= files
59 - use the
=foo.rs=,
=foo/*= pattern instead
60 - derive
=Debug= and
=Clone= always
61 - write a sensible
=Display= impl
62 - derive default methods for
=Default=,
=Hash=,
=Copy=, etc where possible
63 - use generics where appropriate:
=foo<P:AsRef<Path>>(path:P){p.as_ref();}=
