Documentation, Style and Project Layout

52.1 Project Layout

Scaffolding: cl-project ((cl-project:make-project #p"~/projects/my-app/")), Roswell templates, or quickproject.

my-app/
├── my-app.asd             ; system definitions (main, tests, executable)
├── README.md
├── LICENSE
├── src/
│   ├── package.lisp       ; defpackage forms
│   ├── utils.lisp
│   ├── model.lisp
│   └── main.lisp
├── tests/
│   └── main.lisp
├── qlfile / qlfile.lock    ; Qlot dependency pinning (optional), or ocicl.csv
└── .github/workflows/ci.yml

52.2 Documentation

Generate documentation with Staple, Declt (Texinfo), coo, or mgl-pax (literate docs with live examples). Docstrings on functions, classes, slots, generic functions, packages, and systems are retrievable at runtime.

(defun area (radius)
  "Return the area of a circle with RADIUS.

RADIUS must be a non-negative real number."
  (* pi radius radius))
(documentation 'area 'function)

52.3 Style Guidelines

Follow the Google Common Lisp Style Guide and the community conventions:

kebab-case, *specials*, +constants+, predicate-p, make-thing

Indent with Emacs/SLIME standard indentation, and keep lines short

Prefer functions over macros, let over setf of new variables, and defparameter for configuration

Use check-type/assert for argument validation in public APIs

Use handler-case sparingly at boundaries; signal specific condition types

Don't use eval in normal code; don't mutate literal constants

Keep packages small and export a clear API Linting: sblint (SBCL warnings), lisp-critic, and compiler style warnings (undefined variables and functions are reported at compile time).