(elisp)Comment Tips


Next: Library Headers Prev: Documentation Tips Up: Tips

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
     inserted.

     (The 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 are used
     to 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)))

     These comments are also written before a function definition to
     explain what the function does and how to call it properly.

`;;;'
     Comments that start with three semicolons, `;;;', should start at
     the left margin.  Such comments are not used within function
     definitions, but are used to make more general comments.  For
     example:

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

`;;;;'
     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 the
number of semicolons.  Note: Manipulating Comments.

   If you wish to "comment out" a number of lines of code, use triple
semicolons at the beginnings of the lines.

   Any character may be included in a comment, but it is advisable to
precede a character with syntactic significance in Lisp (such as `\' or
unpaired `(' or `)') with a `\', to prevent it from confusing the Emacs
commands for editing Lisp.


automatically generated by info2www