lisp

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