Lyrics
Learn
Wiki
News
Community
Style Guide
Introduction
This is an opinionated guide to writing good, maintainable Common Lisp code.
This page is largely based on Google’s Common Lisp Style Guide and Ariel Networks’ own guide.
Contents
Introduction
Contents
General Guidelines
Use Libraries
Write Libraries
Naming
General style
Variables
Predicates
Don’t prefix package names
Formatting
Indentation
Line length
File header
Documentation
Docstrings everywhere
Comment Hierarchy
Do not use comments to erase code
CLOS
Slot options
Use the :TYPE slot option
Flow Control
Use WHEN, UNLESS
Keep conditions short
Packages
One Package Per File
Avoid :USE
Hierarchical Package Names
Project Structure
Directory Structure
System Definitions
The README
Use Continuous Integration services
General Guidelines
Use Libraries
Look for libraries that solve the problems you are trying to solve before embarking on a project. Making a project with no dependencies is not some sort of virtue. It doesn’t aid portability and it doesn’t help when it comes to turning a Lisp program into an executable.
Writing a library that solves the same problem as another hurts consolidation. Generally, you should only do this if you are going to make it worth it: Good, complete documentation, examples, and a well-designed website are – taken together – a good reason to write an alternative library to an existing one.
As always, check the licensing information of the libraries you use for incompatibilities.
Write Libraries
Before starting a project, think about its structure: Does every component have to be implemented within the project? Or are there parts that might be usable by others? If so, split the project into libraries.
If you set out to write a vast monolith and then lose interest, you will end up with 30% of an ambitious project, completely unusable to others because it’s bound to the rest of the unfinished code.
If you think of your project as a collection of independent libraries, bound together by a thin layer of domain-specific functionality, then if you lose interest in a project you will have left a short trail of useful libraries for others to use and build upon.
In short: write many small libraries.
Naming
General style
Names are lowercase, separated by single dashes (-), and they are complete words. That is, you should write user-count rather than user-cnt and make-text-node is better mk-txt-node.
Variables
Special variables (Mutable globals) should be surrounded by asterisks. These are called earmuffs.
For example:
(defparameter *positions* (make-array ...))
(defparameter *db* (make-hash-table))
Constants should be surrounded with plus signs. For example:
(defconstant +golden-ratio+ 1.6180339)
(defconstant +allowed-operators+ '(+ - * / expt))
Predicates
A predicate is a function that, given some input, returns
