D.7 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 depends on whether the comment should be considered a “heading” by Outline minor mode. By default, comments starting with at least three semicolons (followed by a single space and a non-whitespace character) are considered headings, comments starting with two or less are not.

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. By default, Outline minor mode does not consider a comment to be a heading (even if it starts with at least three semicolons) if the semicolons are followed by at least two spaces. Thus, if you add an introductory comment to the commented out code, make sure to indent it by at least two spaces after the three semicolons.

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

When commenting out entire functions, use two semicolons.

‘;;;;’

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. Voir (emacs)Comments section `Manipulating Comments' dans The GNU Emacs Manual.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.