Up: Tips   [Contents][Index]


5.42.1 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 Jade’s Lisp mode the command Meta-; can be used to insert a comment of this type.

For example,

(defconst op-call #x08)         ;call (stk[n] stk[n-1] ... stk[0])
                                ; pops n values, replacing the
                                ; function with the result.
(defconst op-push #x10)         ;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,

(let
    ((fname (concat file-name ?c)))
  ;; Be sure to remove any partially written dst-file.
  (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.


Up: Tips   [Contents][Index]