Next: Library Headers Prev: Documentation Tips Up: Tips
Tips on Writing Comments
We recommend these conventions for where to put comments and how to
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
(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
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
;;; 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