[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

D. Tips and Conventions

This chapter describes no additional features of Emacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters, and describes conventions Emacs Lisp programmers should follow.

You can automatically check some of the conventions described below by running the command M-x checkdoc RET when visiting a Lisp file. It cannot check all of the conventions, and not all the warnings it gives necessarily correspond to problems, but it is worth examining them all.

D.1 Emacs Lisp Coding Conventions  Conventions for clean and robust programs.
D.2 Tips for Making Compiled Code Fast  Making compiled code run fast.
D.3 Tips for Documentation Strings  Writing readable documentation strings.
D.4 Tips on Writing Comments  Conventions for writing comments.
D.5 Conventional Headers for Emacs Libraries  Standard headers for library packages.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

D.1 Emacs Lisp Coding Conventions

Here are conventions that you should follow when writing Emacs Lisp code intended for widespread use:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

D.2 Tips for Making Compiled Code Fast

Here are ways of improving the execution speed of byte-compiled Lisp programs.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

D.3 Tips for Documentation Strings

Here are some tips and conventions for the writing of documentation strings. You can check many of these conventions by running the command M-x checkdoc-minor-mode.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

D.4 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

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. See section `Manipulating Comments' in The GNU Emacs Manual.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

D.5 Conventional Headers for Emacs Libraries

Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote them. This section explains these conventions.

We'll start with an example, a package that is included in the Emacs distribution.

Parts of this example reflect its status as part of Emacs; for example, the copyright notice lists the Free Software Foundation as the copyright holder, and the copying permission says the file is part of Emacs. When you write a package and post it, the copyright holder would be you (unless your employer claims to own it instead), and you should get the suggested copying permission from the end of the GNU General Public License itself. Don't say your file is part of Emacs if we haven't installed it in Emacs yet!

With that warning out of the way, on to the example:

;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers

;; Copyright (C) 1992 Free Software Foundation, Inc.

;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
;; Created: 14 Jul 1992
;; Version: 1.2
;; Keywords: docs

;; This file is part of GNU Emacs.
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

The very first line should have this format:

;;; filename --- description

The description should be complete in one line.

After the copyright notice come several header comment lines, each beginning with `;; header-name:'. Here is a table of the conventional possibilities for header-name:

This line states the name and net address of at least the principal author of the library.

If there are multiple authors, you can list them on continuation lines led by ;; and a tab character, like this:

;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
;;      Dave Sill <de5@ornl.gov>
;;      Dave Brennan <brennan@hal.com>
;;      Eric Raymond <esr@snark.thyrsus.com>

This line should contain a single name/address as in the Author line, or an address only, or the string `FSF'. If there is no maintainer line, the person(s) in the Author field are presumed to be the maintainers. The example above is mildly bogus because the maintainer line is redundant.

The idea behind the `Author' and `Maintainer' lines is to make possible a Lisp function to "send mail to the maintainer" without having to mine the name out by hand.

Be sure to surround the network address with `<...>' if you include the person's full name as well as the network address.

This optional line gives the original creation date of the file. For historical interest only.

If you wish to record version numbers for the individual Lisp program, put them in this line.

In this header line, place the name of the person who adapted the library for installation (to make it fit the style conventions, for example).

This line lists keywords for the finder-by-keyword help command. Please use that command to see a list of the meaningful keywords.

This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both.

Just about every Lisp library ought to have the `Author' and `Keywords' header comment lines. Use the others if they are appropriate. You can also put in header lines with other header names--they have no standard meanings, so they can't do any harm.

We use additional stylized comments to subdivide the contents of the library file. These should be separated by blank lines from anything else. Here is a table of them:

`;;; Commentary:'
This begins introductory comments that explain how the library works. It should come right after the copying permissions, terminated by a `Change Log', `History' or `Code' comment line. This text is used by the Finder package, so it should make sense in that context.

`;;; Documentation'
This has been used in some files in place of `;;; Commentary:', but `;;; Commentary:' is preferred.

`;;; Change Log:'
This begins change log information stored in the library file (if you store the change history there). For Lisp files distributed with Emacs, the change history is kept in the file `ChangeLog' and not in the source file at all; these files generally do not have a `;;; Change Log:' line. `History' is an alternative to `Change Log'.

`;;; Code:'
This begins the actual code of the program.

`;;; filename ends here'
This is the footer line; it appears at the very end of the file. Its purpose is to enable people to detect truncated versions of the file from the lack of a footer line.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on May 2, 2002 using texi2html