Over the years I've read many many Lisp programs. Some were written by others and some were written by me months or years earlier (so to me it was like looking at a program I'd never seen before). I've noticed what makes it hard to read and understand a program and what makes it a pleasure to read. I wrote this document as a reminder to myself of the rules I must follow to write readable Lisp code. I intend to keep extending the set of rules as time permits.
This document describes a Lisp coding standard designed primarily to increase code readability. Files that follow this standard may be marked with the url http://www.franz.com/~jkf/coding_standards.html.
Note well: The document contains the opinions of its author (John Foderaro) only and may or may not reflect the opinions of anyone else at Franz Inc and definitely do not denote an official policy of Franz Inc which has graciously permitted the author the use of its web server to store this page.
It has been noted that a program is written only once yet read many times. Thus program readability has to be a primary concern of the programmer. It's likely that the person reading your code will have far less knowledge of how you've solved the problem at hand than you have at the time you wrote the code. Thus you must strive to make your code readable by someone with little knowledge of the code.
I've found that the key to readability in Lisp functions is an obvious structure or framework to the code. With a glance you should be able to see where objects are bound, iteration is done and most importantly where conditional branching is done. The conditionals are the most important since this is where the program is deciding what to do next. Bugs often occur when the conditional can't handle all possible cases. If you're planning on extending the function you need a clear idea of the possible inputs it's willing to accept and what you can assert to be true for each branch of the conditional.
Thus to me the most important expression in one's code is the conditional expression. These must be expressed as clearly as possible. Common Lisp offers four conditional expressions: cond, if, when and unless. Common Lisp also provides a powerful macro facility that permits you to extend the language. I chose to use the macro facility to extend the language to create a conditional expression that I felt gave me the readability that the conditional expression should have. This macro is called if*. The source code for if* can be found here and the documentation here.
The if* macro along with proper indenting support in the editor makes glaringly apparent the structure of conditionals. They stand out like a sore thumb. Furthermore one can easily extend an if* conditional adding expressions to the then or else clauses or adding more predicates with elseif. Thus once you've laid out the conditional you can easily extend it without changing the expression itself (contrast that to having to go from when to if to cond as you grow the conditional using the built-in Common Lisp conditional forms).
Now that we've introduced if* here are the coding rules;