Comment Styles

As already described, single-line comments in Lisp are introduced by a semi-colon (`;') character. By convention a different number of semi-colons is used to introduce different types of comments,

`;'

A comment referring to the line of Lisp code that it occurs on, comments of this type are usually indented to the same depth, on the right of the Lisp code. When editing in Lisp mode the command Meta-; can be used to insert a comment of this type. For example,

(defconst op-call 0x08)	        ;call (stk[n] stk[n-1] ... stk[0])
                                ; pops n values, replacing the
                                ; function with the result.
(defconst op-push 0x10)	        ;pushes constant # n

`;;'

Comments starting with two semi-colons are written on a line of their own and indented to the same depth as the next line of Lisp code. They describe the following lines of code. For example,

;; Be sure to remove any partially written dst-file.
(let
    ((fname (concat file-name ?c)))
  (when (file-exists-p fname)
    (delete-file fname)))

Comments of this type are also placed before a function definition to describe the function. This saves wasting memory with a documentation string in a module's internal functions. For example,

;; Compile a form which occurred at the `top-level' into a
;; byte code form.
;; defuns, defmacros, defvars, etc... are treated specially.
;; require forms are evaluated before being output uncompiled;
;; this is so any macros are brought in before they're used.
(defun comp-compile-top-form (form)
  ...

`;;;'

This type of comment always starts in the first column of the line, they are used to make general comments about a program and don't refer to any function or piece of code in particular. For example,

;;; Notes:
;;;
;;; Instruction Encoding
;;; ====================
;;; Instructions which get an argument (with opcodes of zero up to
...

`;;;;'

Each program should have a comment of this type as its first line, the body of the comment is the name of the file, two dashes and a brief description of what the program does. They always start in the first column. For example,

;;;; compiler.jl -- Simple compiler for Lisp files/forms

If you adhere to these standards the indentation functions provide by the Lisp mode will indent your comments to the correct depth.

Go to the first, previous, next, last section, table of contents.