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)?

Solution 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].

Solution 2

Multiline comments #| |# are often used to comment out larger amounts of Lisp code or example code. Since some Emacs implementations seem to have trouble parsing them, some are using #|| ||# instead.

For the use of semicolons see the comment example in the book Common Lisp the Language (page 348), 1984, Digital Press, by Guy L. Steele Jr.:

;;;; COMMENT-EXAMPLE function. 
;;; This function is useless except to demonstrate comments. 
;;; (Actually, this example is much too cluttered with them.) 

(defun comment-example (x y)      ;X is anything; Y is an a-list. 
  (cond ((listp x) x)             ;If X is a list, use that. 
        ;; X is now not a list.  There are two other cases. 
        ((symbolp x) 
        ;; Look up a symbol in the a-list. 
        (cdr (assoc x y)))        ;Remember, (cdr nil) is nil. 
        ;; Do this when all else fails: 
        (t (cons x                ;Add x to a default list. 
                 '((lisp t)       ;LISP is okay. 
                   (fortran nil)  ;FORTRAN is not. 
                   (pl/i -500)    ;Note that you can put comments in 
                   (ada .001)     ; "data" as well as in "programs". 
                   ;; COBOL?? 
                   (teco -1.0e9))))))

In this example, comments may begin with one to four semicolons.

• Single-semicolon comments are all aligned to the same column at the right; usually each comment concerns only the code it is next to. Occasionally a comment is long enough to occupy two or three lines; in this case, it is conventional to indent the continued lines of the comment one space (after the semicolon).

• Double-semicolon comments are aligned to the level of indentation of the code. A space conventionally follows the two semicolons. Such comments usually describe the state of the program at that point or the code section that follows the comment.

• Triple-semicolon comments are aligned to the left margin. They usually document whole programs or large code blocks.

• Quadruple-semicolon comments usually indicate titles of whole programs or large code blocks.

Solution 3

The standard reference for Common Lisp style, including commenting conventions, is Peter Norvig and Kent Pitman's Tutorial on Good Lisp Programming Style.

Solution 4

Instead of describing it here, have a look at this page. It's talking about Emacs Lisp, but the convention are the same across all lisps (and schemes).

Solution 5

It's annoying that people refer to conventions without explaining what's wrong with using double semicolons with end-of-line-comments.

There's nothing wrong per-se with using double semicolons with so called "margin" (end-of-line) comments. It may become a problem though if you want to have margin comments and regular comments in the same block, e.g.:

   (defn foo []
      (bar) ;; yup, bar
      ;; let's now do a zap
      (zap))

So, if you use fill-paragraph feature of Emacs - it will automatically align both those comments as if they were a single statement.

   (defn foo []
      (bar) ;; yup, bar
            ;; let's now do a zap
      (zap))

And that's not what you probably want. So if use a single semicolon instead:

   (defn foo []
      (bar) ; yup, bar
      ;; let's now do a zap
      (zap))

It will keep it as intended. So instead explaining this over and over again, I guess people just made a rule - use single semicolon for margin comments

View more solutions

Comments

[Susam Pal]

Section 2.4.4.2 of CLHS talks about this here: lispworks.com/documentation/HyperSpec/Body/02_ddb.htm

[compman]

Thanks! (Why is there a minimum number of characters required in comments?)

[Svante]

You can use any word not designating a feature for the #+nil part, e.g. #+todo, #+alternative-version, #+perhaps-needed-later.

[Svante]

@Eli Barzilay: He meant the Stackoverflow comment boxes. :)

[compman]

@Eli: I just got why you were confused.

[Rainer Joswig]

If Emacs makes a problem with #| |# use #|| ||# .

[Devon]

#+nil to comment out code insults the implementors of NIL (New Implementation of Lisp) so I'd suggest #+|| #+\; or similar.