Lisp commenting convention

Question

What is the Lisp convention about how many semicolons to use for different kinds of comments (and what the level of indentation for various numbers of semicolons should be)?

Also, is there any convention about when to use semicolon comments and when to use #|multiline comments|# (assuming they exist and exist on multiple implementations)?

Answer 1

In Common Lisp:

;;;; At the top of source files

;;; Comments at the beginning of the line

(defun test (a &optional b)
  ;; Commends indented along with code
  (do-something a)                      ; Comments indented at column 40, or the last
  (do-something-else b))                ; column + 1 space if line exceeds 38 columns

Note: Emacs doesn't fontify #| |# very well, but as Rainer suggests in the comments, try using #|| ||# instead.

I'd say there are no rules to use this one, but I reckon it's faster for commenting huge amounts of code, or to insert some long description where the semicolons just get in the way of editing, like huge BNF listings or the like.

There's a neat trick to disable code which is to prefix an expression with #+(or):

(defun test (a &optional b)
  #+(or)
  (do-something a)
  (do-something-else b))

Note: #+nil usually works too, unless you happen to have a nil or :nil feature. The advantage of #+(or) is that you can edit it easily by either commenting it out or change it to #+(and), or to actually include a set of features upon which you really want that expression to be read.

SLIME helps here by fontifying the form (do-something a) as a comment when you have a Lisp running.

Apart from Common Lisp's particular commenting syntax and tricks, such as #| |# and #+(or) or the more commonly seen #+nil, I believe the semicolon rules are widely adopted in other lisps too.

---

Here's an excerpt from the specification, note how current practice has diverged regarding the single semicolon:

2.4.4.2 Notes about Style for Semicolon

Some text editors make assumptions about desired indentation based on the number of semicolons that begin a comment. The following style conventions are common, although not by any means universal.

2.4.4.2.1 Use of Single Semicolon

Comments that begin with a single semicolon are all aligned to the same column at the right (sometimes called the “comment column”). The text of such a comment generally applies only to the line on which it appears. Occasionally two or three contain a single sentence together; this is sometimes indicated by indenting all but the first with an additional space (after the semicolon).

2.4.4.2.2 Use of Double Semicolon

Comments that begin with a double semicolon are all aligned to the same level of indentation as a form would be at that same position in the code. The text of such a comment usually describes the state of the program at the point where the comment occurs, the code which follows the comment, or both.

2.4.4.2.3 Use of Triple Semicolon

Comments that begin with a triple semicolon are all aligned to the left margin. Usually they are used prior to a definition or set of definitions, rather than within a definition.

2.4.4.2.4 Use of Quadruple Semicolon

Comments that begin with a quadruple semicolon are all aligned to the left margin, and generally contain only a short piece of text that serve as a title for the code which follows, and might be used in the header or footer of a program that prepares code for presentation as a hardcopy document.

2.4.4.2.5 Examples of Style for Semicolon

;;;; Math Utilities

;;; FIB computes the the Fibonacci function in the traditional
;;; recursive way.

(defun fib (n)
  (check-type n integer)
  ;; At this point we're sure we have an integer argument.
  ;; Now we can get down to some serious computation.
  (cond ((< n 0)
         ;; Hey, this is just supposed to be a simple example.
         ;; Did you really expect me to handle the general case?
         (error "FIB got ~D as an argument." n))
        ((< n 2) n)             ;fib[0]=0 and fib[1]=1
        ;; The cheap cases didn't work.
        ;; Nothing more to do but recurse.
        (t (+ (fib (- n 1))     ;The traditional formula
              (fib (- n 2)))))) ; is fib[n-1]+fib[n-2].