CODEWITHSUNDEEP
lispcommon-lispcommentselispconventions
matj1
matj1

Reputation: 330

Why do Lisp style guides recommend the specific numbers of semicolons for comment in several cases?

I read in the style guide of Elisp and of Common Lisp to use specific numbers of semicolons in various cases, in short this:

Specifically, why are double semicolons supposed to be used in comments on their own lines? Why did someone decide to do it that way? It seems that double semicolons do not add any information because it is obvious that the comments are on their own lines, and I don't see any other purpose for them. I prefer using single semicolons there and decrease the number of semicolons in the following cases (so two for documentation).

Upvotes: 2

Views: 124

Answers (1)

ignis volens
ignis volens

Reputation: 9282

I do not know the history, or even if the history is completely known. I have used Lisps which did not have ; as a comment character (rather %) but I do not now remember whether they had the same convention.

But what matters is that it is a convention: if you follow the convention other people will be able to read your code, and other people's editors will be able to handle your code. Using some different convention for comments, just as using a different convention for indentation, is a way of making programs you write less usable by other people. If you're the only person who will ever look at them, do what you will, of course.

The current convention has some noticeable advantages, however.

(defun foo (x)
  ;; conventional comment saying what FOO does
  (let ((d (ccm x)))                    ;note things about d here but
                                        ;this note is quite long
    ;; This comment does not continue from the previous one, but
    ;; rather describes some things about this part of the code.
;;; This is all broken
;;;     (when (< d *the-mass*)
;;;       (let* ((r (radiation-case-size d)))
;;;         (commission (manufacture-radiation-case r) d r)))
     d))

As you can see, the distinction between a trailing comment which happens to span two lines and the following interline comment matters here. And the intentioanlly-ugly three-colon comments within the function indicate immediately that something odd is going on, and in particular that the function has parts of itself commented out.

Similarly the use of four semicolons for section headers is typographicaly useful: it helps people read long toplevel comments which are divided into sections, with titles.

Upvotes: 5

Related Questions