Lisp Style Tips for the Beginner

Heinrich Taube

Composition/Theory -- School of Music -- University of Illinois,,

This document is an informal compendium of beginner's tips on how to develop an efficient, legible style of Lisp coding.



Symbols and Variables




Avoid using do, which is almost impossible to read. dotimes and dolist are fine for simple iteration. If you need to save, store or modify results of an iteration, then loop is probably the most legible and efficient construct to use. Some Lisp programmers avoid loop because it does not "look like lisp". Loop is nevertheless a convenient and very powerful facility. After 10 minutes of working with do, most Lisp programmers are glad to have loop around!


Provide them. Document overall functionality and explain sections of code that are a bit tricky (you will forget how you implemented something in about 2 week's time.) Lisp provides two different types of comments. The semi-colon ; introduces a line-oriented comment. Lisp ignores whatever follows a semi-colon until the end of the line that the semi-colon is on. The semi-colon does not have to be the first character in the line. Here are two examples:

; this is a comment
(abs x) ; need absolute value here!
By convention, Lisp programmers distinguish between one, two or three semi-colon comments. A comment introduced by a single semi-colon explains code on the same line as the comment. Two semi-colons mean that the comment is a description about the state of the program at that point, or an explanation of the next section of code. A two semi-colon comment should start at the same indentation column as the code it documents. A three semi-colon comment provides a global explanation and always starts at the left margin. Here is an example containing all three types:
;;;  the next 20 functions do various sorts of frobbing
(defun frob1 (num)
  ;; return double frob of num
  (let ((tmp (random num)))      ; breaks if 0, fix!
    (double-frob tmp num :with-good-luck t)))
Block comments are made by placing text within #| and |#. Lisp ignores anything between the balancing delimiters no matter how may lines of text are included. #| |# pairs are often used to comment out large sections of program code in a file or function. For example:
;;; i think this function is obsolete.
(defun frob2 (list)
  (frob-aux (first list)))
comments out a function definition that is no longer used.

Formatting and Indentation

Poorly formatted Lisp code is difficult to read. The most important prerequisite for legible Lisp code is a simple, consistent style of indentation. Some text editors, such as Emacs or Fred, understand Lisp syntax and will automatically perform this task for you. Other text editors, such as NeXTStep's, have no understanding of Lisp beyond parentheses matching. Even if you use a text editor that cannot perform Lisp indentation, you should take the time to format your code properly. Here are a few simple rules to follow: