The Compiler Company Styleguide

As an organization we maintain a styleguide1 which lists all of the style guidelines we use for our code. If you are contributing to one of our projects, you should review and understand the relevant sections below.

You should also review the ulang document, which may shine some light on code comments and developer docs.

1. General Programming

  • indent-offset = 2
  • max-line-width = 80
  • page-length ~ 32
  • module-length ~ 512
  • file-size ~ 1024
  • start every source-file with a header comment
  • use outline headings to organize your program
  • use ulang-comments as needed for referencing bugs, notes, etc.
  • inline documentation should be declarative. your code explains your comments for you.
  • variables, imports, and exports belong at the top of a file
  • main functions belong at the bottom of a file
  • use LSP wherever possible (eglot, slime)

2. Common Lisp

  • prefer symbol docs to comments
  • use stdin/stdout/stderr correctly - see CDR-11
  • always prefer core libraries over vendored dependencies
  • use the compiler built-ins - if a function or class is generally useful, add it to the core
  • use conditions, restarts, and error handling where appropriate
  • save type declarations and hairy optimizations for when the API is polished
  • don't be afraid of macros

2.1. Systems

  • define systems using keyword symbols
  • use slash instead of dash for path separation in system names: :foo/bar
  • define your test system in the same file with a name of: :foo/tests
  • where possible, avoid collisions with systems in Quicklisp

2.2. Packages

  • declare packages in a file named pkg.lisp
  • when multiple packages are being declared, consider a wrapper package
    • declare with UIOP:DEFINE-PACKAGE and :USE-REEXPORT
  • package names are either the same as their system name or have the system name as their root path.
  • use :NICKNAMES to declare alternative names for your package

2.3. CLOS

  • prefer :default-initargs over :initform.

3. Rust

  • always prefer core libraries to vendored dependencies
  • don't make mod.rs files
    • use the foo.rs, foo/* pattern instead
  • derive Debug and Clone always
  • write a sensible Display impl
  • derive default methods for Default, Hash, Copy, etc where possible
  • use generics where appropriate: foo<P:AsRef<Path>>(path:P){p.as_ref();}

4. Emacs Lisp

5. Org-mode

6. Shell

7. Python

Footnotes:

1

https://google.github.io/styleguide/