GNU Info

(librep.info)Comment Styles

---

Up: Tips

---

Enter node , (file) or (file)node

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.