1.1--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2+++ b/style.org	Sun Aug 11 10:09:31 2024 -0400
     1.3@@ -0,0 +1,66 @@
     1.4+#+title: The Compiler Company Styleguide
     1.5+#+author: Richard Westhaver
     1.6+#+email: ellis@rwest.io
     1.7+#+setupfile: ../../clean.theme
     1.8+As an organization we maintain a styleguide[fn:1] which lists all of
     1.9+the style guidelines we use for our code. If you are contributing to
    1.10+one of our projects, you should review and understand the relevant
    1.11+sections below.
    1.12+
    1.13+You should also review the [[file:ulang.org][ulang]] document, which may shine some light
    1.14+on code comments and developer docs.
    1.15+
    1.16+[fn:1] https://google.github.io/styleguide/ 
    1.17+
    1.18+* General Programming
    1.19+- indent-offset = 2
    1.20+- max-line-width = 80
    1.21+- page-length ~ 32
    1.22+- module-length ~ 512
    1.23+- file-size ~ 1024
    1.24+
    1.25+- start every source-file with a header comment
    1.26+- use outline headings to organize your program
    1.27+- use ulang-comments as needed for referencing bugs, notes, etc.
    1.28+- inline documentation should be declarative. your code explains your
    1.29+  comments for you.
    1.30+- variables, imports, and exports belong at the top of a file
    1.31+- =main= functions belong at the bottom of a file
    1.32+- use LSP wherever possible (eglot, slime)
    1.33+* Common Lisp
    1.34+- prefer symbol docs to comments
    1.35+- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]]
    1.36+- always prefer =core= libraries over vendored dependencies
    1.37+- use the compiler built-ins - if a function or class is generally
    1.38+  useful, add it to the core
    1.39+- use conditions, restarts, and error handling where appropriate
    1.40+- save type declarations and hairy optimizations for when the API is
    1.41+  polished
    1.42+- don't be afraid of macros
    1.43+** Systems
    1.44+- define systems using keyword symbols
    1.45+- use slash instead of dash for path separation in system names: =:foo/bar=
    1.46+- define your test system in the same file with a name of: =:foo/tests=
    1.47+- where possible, avoid collisions with systems in Quicklisp
    1.48+** Packages
    1.49+- declare packages in a file named =pkg.lisp=
    1.50+- when multiple packages are being declared, consider a wrapper
    1.51+  package
    1.52+  - declare with ~UIOP:DEFINE-PACKAGE~ and ~:USE-REEXPORT~
    1.53+- package names are either the same as their system name or have the
    1.54+  system name as their root path.
    1.55+- use ~:NICKNAMES~ to declare alternative names for your package
    1.56+** CLOS
    1.57+- prefer =:default-initargs= over =:initform=.
    1.58+* Rust
    1.59+- always prefer =core= libraries to vendored dependencies
    1.60+- don't make =mod.rs= files
    1.61+  - use the =foo.rs=, =foo/*= pattern instead
    1.62+- derive =Debug= and =Clone= always
    1.63+- write a sensible =Display= impl
    1.64+- derive default methods for =Default=, =Hash=, =Copy=, etc where possible
    1.65+- use generics where appropriate: =foo<P:AsRef<Path>>(path:P){p.as_ref();}=
    1.66+* Emacs Lisp
    1.67+* Org-mode
    1.68+* Shell
    1.69+* Python