GNU Info

(elisp)Comment Tips

---

Next: Library Headers Prev: Documentation Tips Up: Tips

---

Enter node , (file) or (file)node

Tips on Writing Comments
========================

   We recommend these conventions for where to put comments and how to
indent them:

`;'
     Comments that start with a single semicolon, `;', should all be
     aligned to the same column on the right of the source code.  Such
     comments usually explain how the code on the same line does its
     job.  In Lisp mode and related modes, the `M-;'
     (`indent-for-comment') command automatically inserts such a `;' in
     the right place, or aligns such a comment if it is already present.

     This and following examples are taken from the Emacs sources.

          (setq base-version-list                 ; there was a base
                (assoc (substring fn 0 start-vn)  ; version to which
                       file-version-assoc-list))  ; this looks like
                                                  ; a subversion

`;;'
     Comments that start with two semicolons, `;;', should be aligned to
     the same level of indentation as the code.  Such comments usually
     describe the purpose of the following lines or the state of the
     program at that point.  For example:

          (prog1 (setq auto-fill-function
                       ...
                       ...
            ;; update mode line
            (force-mode-line-update)))

     We also normally use two semicolons for comments outside functions.

          ;; This Lisp code is run in Emacs
          ;; when it is to operate as a server
          ;; for other processes.

     Every function that has no documentation string (presumably one
     that is used only internally within the package it belongs to),
     should instead have a two-semicolon comment right before the
     function, explaining what the function does and how to call it
     properly.  Explain precisely what each argument means and how the
     function interprets its possible values.

`;;;'
     Comments that start with three semicolons, `;;;', should start at
     the left margin.  These are used, occasionally, for comments within
     functions that should start at the margin.  We also use them
     sometimes for comments that are between functions--whether to use
     two or three semicolons there is a matter of style.

     Another use for triple-semicolon comments is for commenting out
     lines within a function.  We use three semicolons for this
     precisely so that they remain at the left margin.

          (defun foo (a)
          ;;; This is no longer necessary.
          ;;;  (force-mode-line-update)
            (message "Finished with %s" a))

`;;;;'
     Comments that start with four semicolons, `;;;;', should be aligned
     to the left margin and are used for headings of major sections of a
     program.  For example:

          ;;;; The kill ring

The indentation commands of the Lisp modes in Emacs, such as `M-;'
(`indent-for-comment') and <TAB> (`lisp-indent-line'), automatically
indent comments according to these conventions, depending on the number
of semicolons.  Note: Manipulating Comments.


automatically generated by info2www version 1.2.2.9