We recommend these conventions for where to put comments and how to indent them:
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
(prog1 (setq auto-fill-function
...
...
;; update modeline
(redraw-modeline)))
Every function that has no documentation string (because it is use only
internally within the package it belongs to), should have instead 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.
;;; This Lisp code is run in XEmacs ;;; when it is to operate as a server ;;; for other processes.Another use for triple-semicolon comments is for commenting out lines within a function. We use triple-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))
;;;; The kill ring
The indentation commands of the Lisp modes in XEmacs, 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. See section `Manipulating Comments' in The XEmacs Reference Manual.