Next: Previous:
42. 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.
top next
42.1. Emacs
Lisp Coding Conventions
Here are conventions that you should follow when writing Emacs
Lisp code intended for widespread use:
- Since all global variables share the same name space, and all
functions share another name space, you should choose a short word
to distinguish your program from other Lisp programs. Then take
care to begin the names of all global variables, constants, and
functions with the chosen prefix. This helps avoid name conflicts.
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp--even to
copy-list
. Believe it or not, there is more than one
plausible way to define copy-list
. Play it safe;
append your name prefix to produce a name like
foo-copy-list
or mylib-copy-list
instead.
If you write a function that you think ought to be added to Emacs
under a certain name, such as twiddle-files
, don't
call it by that name in your program. Call it
mylib-twiddle-files
in your program, and send mail to
`bug-gnu-emacs@gnu.org' suggesting we add it to Emacs.
If and when we do, we can change the name easily enough. If one
prefix is insufficient, your package may use two or three
alternative common prefixes, so long as they make sense. Separate
the prefix from the rest of the symbol name with a hyphen,
`-'. This will be consistent with Emacs itself and
with most Emacs Lisp programs.
- It is often useful to put a call to
provide
in
each separate library program, at least if there is more than one
entry point to the program.
- If a file requires certain other library programs to be loaded
beforehand, then the comments at the beginning of the file should
say so. Also, use
require
to make sure they are
loaded.
- If one file foo uses a macro defined in another file
bar, foo should contain this expression
before the first use of the macro:
(eval-when-compile (require 'bar))
(And the library bar should contain (provide
'bar)
, to make the require
work.)
This will cause bar to be loaded when you byte-compile
foo. Otherwise, you risk compiling foo
without the necessary macro loaded, and that would produce compiled
code that won't work right. See section . Using
eval-when-compile
avoids loading bar when
the compiled version of foo is used.
- When defining a major mode, please follow the major mode
conventions. See section .
- When defining a minor mode, please follow the minor mode
conventions. See section .
- If the purpose of a function is to tell you whether a certain
condition is true or false, give the function a name that ends in
`p'. If the name is one word, add just
`p'; if the name is multiple words, add
`-p'. Examples are
framep
and
frame-live-p
.
- If a user option variable records a true-or-false condition,
give it a name that ends in `-flag'.
- Please do not define C-c
letter as a key in your major modes. These
sequences are reserved for users; they are the
only sequences reserved for users, so do not block
them. Instead, define sequences consisting of C-c
followed by a control character, a digit, or certain punctuation
characters. These sequences are reserved for major modes. Changing
all the Emacs major modes to follow this convention was a lot of
work. Abandoning this convention would make that work go to waste,
and inconvenience users.
- Sequences consisting of C-c followed by
{, }, <, >,
: or ; are also reserved for major
modes.
- Sequences consisting of C-c followed by any other
punctuation character are allocated for minor modes. Using them in
a major mode is not absolutely prohibited, but if you do that, the
major mode binding may be shadowed from time to time by minor
modes.
- Function keys F5 through F9 without
modifier keys are reserved for users to define.
- Do not bind C-h following any prefix character
(including C-c). If you don't bind C-h, it is
automatically available as a help character for listing the
subcommands of the prefix character.
- Do not bind a key sequence ending in ESC except
following another ESC. (That is, it is OK to bind a
sequence ending in ESC ESC.) The
reason for this rule is that a non-prefix binding for
ESC in any context prevents recognition of escape
sequences as function keys in that context.
- Anything which acts like a temporary mode or state which the
user can enter and leave should define ESC
ESC of ESC ESC
ESC as a way to escape. For a state which accepts
ordinary Emacs commands, or more generally any kind of state in
which ESC followed by a function key or arrow key is
potentially meaningful, then you must not define
ESC ESC, since that would preclude
recognizing an escape sequence after ESC. In these
states, you should define ESC ESC
ESC as the way to escape. Otherwise, define
ESC ESC instead.
- Applications should not bind mouse events based on button 1
with the shift key held down. These events include
S-mouse-1, M-S-mouse-1,
C-S-mouse-1, and so on. They are reserved for
users.
- Special major modes used for read-only text should usually
redefine mouse-2 and RET to trace some sort
of reference in the text. Modes such as Dired, Info, Compilation,
and Occur redefine it in this way.
- When a package provides a modification of ordinary Emacs
behavior, it is good to include a command to enable and disable the
feature, Provide a command named
whatever-mode
which turns the feature on or
off, and make it autoload (see section ). Design the package so that
simply loading it has no visible effect--that should not enable the
feature. Users will request the feature by invoking the
command.
- It is a bad idea to define aliases for the Emacs primitives.
Use the standard names instead.
- Redefining (or advising) an Emacs primitive is discouraged. It
may do the right thing for a particular program, but there is no
telling what other programs might break as a result.
- If a file does replace any of the functions or library programs
of standard Emacs, prominent comments at the beginning of the file
should say which functions are replaced, and how the behavior of
the replacements differs from that of the originals.
- Please keep the names of your Emacs Lisp source files to 13
characters or less. This way, if the files are compiled, the
compiled files' names will be 14 characters or less, which is short
enough to fit on all kinds of Unix systems.
- Don't use
next-line
or previous-line
in programs; nearly always, forward-line
is more
convenient as well as more predictable and robust. See section .
- Don't call functions that set the mark, unless setting the mark
is one of the intended features of your program. The mark is a
user-level feature, so it is incorrect to change the mark except to
supply a value for the user's benefit. See section . In particular, don't use any
of these functions:
beginning-of-buffer
,
end-of-buffer
replace-string
, replace-regexp
If you just want to move point, or replace a certain string,
without any of the other features intended for interactive users,
you can replace these functions with one or two lines of simple
Lisp code.
- Use lists rather than vectors, except when there is a
particular reason to use a vector. Lisp has more facilities for
manipulating lists than for vectors, and working with lists is
usually more convenient. Vectors are advantageous for tables that
are substantial in size and are accessed in random order (not
searched front to back), provided there is no need to insert or
delete elements (only lists allow that).
- The recommended way to print a message in the echo area is with
the
message
function, not princ
. See
section .
- When you encounter an error condition, call the function
error
(or signal
). The function
error
does not return. See section . Do not use
message
, throw
, sleep-for
,
or beep
to report errors.
- An error message should start with a capital letter but should
not end with a period.
- Many commands that take a long time to execute display a
message that says `Operating...' when they start, and
change it to `Operating...done' when they finish.
Please keep the style of these messages uniform: no space
around the ellipsis, and no period at the end.
- Try to avoid using recursive edits. Instead, do what the Rmail
e command does: use a new local keymap that contains one
command defined to switch back to the old local keymap. Or do what
the
edit-options
command does: switch to another
buffer and let the user switch back at will. See section .
- In some other systems there is a convention of choosing
variable names that begin and end with `*'. We don't
use that convention in Emacs Lisp, so please don't use it in your
programs. (Emacs uses such names only for special-purpose buffers.)
The users will find Emacs more coherent if all libraries use the
same conventions.
- Try to avoid compiler warnings about undefined free variables,
by adding
defvar
definitions for these variables. If
you bind a variable in one function, and use it or set it in
another function, the compiler warns about the latter function
unless the variable has a definition. But often these variables
have short names, and it is not clean for Lisp packages to define
such variable names. Therefore, you should rename the variable to
start with the name prefix used for the other functions and
variables in your package.
- Indent each function with C-M-q
(
indent-sexp
) using the default indentation
parameters.
- Don't make a habit of putting close-parentheses on lines by
themselves; Lisp programmers find this disconcerting. Once in a
while, when there is a sequence of many consecutive
close-parentheses, it may make sense to split the sequence in one
or two significant places.
- Please put a copyright notice on the file if you give copies to
anyone. Use a message like this one:
;; Copyright (C) year name
;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2 of
;; the License, or (at your option) any later version.
;; This program is distributed in the hope that it will be
;; useful, but WITHOUT ANY WARRANTY; without even the implied
;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
;; PURPOSE. See the GNU General Public License for more details.
;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
;; MA 02111-1307 USA
If you have signed papers to assign the copyright to the
Foundation, then use `Free Software Foundation, Inc.'
as name. Otherwise, use your name.
top next prev
42.2. Tips for
Making Compiled Code Fast
Here are ways of improving the execution speed of byte-compiled
Lisp programs.
top next prev
42.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.
- Every command, function, or variable intended for users to know
about should have a documentation string.
- An internal variable or subroutine of a Lisp program might as
well have a documentation string. In earlier Emacs versions, you
could save space by using a comment instead of a documentation
string, but that is no longer the case.
- The first line of the documentation string should consist of
one or two complete sentences that stand on their own as a summary.
M-x apropos displays just the first line, and if it
doesn't stand on its own, the result looks bad. In particular,
start the first line with a capital letter and end with a period.
The documentation string can have additional lines that expand on
the details of how to use the function or variable. The additional
lines should be made up of complete sentences also, but they may be
filled if that looks good.
- For consistency, phrase the verb in the first sentence of a
function's documentation string as an infinitive with "to" omitted.
For instance, use "Return the cons of A and B." in preference to
"Returns the cons of A and B." Usually it looks good to do likewise
for the rest of the first paragraph. Subsequent paragraphs usually
look better if they have proper subjects.
- Write documentation strings in the active voice, not the
passive, and in the present tense, not the future. For instance,
use "Return a list containing A and B." instead of "A list
containing A and B will be returned."
- Avoid using the word "cause" (or its equivalents)
unnecessarily. Instead of, "Cause Emacs to display text in
boldface," write just "Display text in boldface."
- Do not start or end a documentation string with
whitespace.
- Format the documentation string so that it fits in an Emacs
window on an 80-column screen. It is a good idea for most lines to
be no wider than 60 characters. The first line can be wider if
necessary to fit the information that ought to be there. However,
rather than simply filling the entire documentation string, you can
make it much more readable by choosing line breaks with care. Use
blank lines between topics if the documentation string is
long.
- Do not indent subsequent lines of a
documentation string so that the text is lined up in the source
code with the text of the first line. This looks nice in the source
code, but looks bizarre when users view the documentation. Remember
that the indentation before the starting double-quote is not part
of the string!
- When the user tries to use a disabled command, Emacs displays
just the first paragraph of its documentation string--everything
through the first blank line. If you wish, you can choose which
information to include before the first blank line so as to make
this display useful.
- A variable's documentation string should start with
`*' if the variable is one that users would often want
to set interactively. If the value is a long list, or a function,
or if the variable would be set only in init files, then don't
start the documentation string with `*'. See section
.
- The documentation string for a variable that is a yes-or-no
flag should start with words such as "Non-nil means...", to make it
clear that all non-
nil
values are equivalent and
indicate explicitly what nil
and non-nil
mean.
- When a function's documentation string mentions the value of an
argument of the function, use the argument name in capital letters
as if it were a name for that value. Thus, the documentation string
of the function
/
refers to its second argument as
`DIVISOR', because the actual argument name is
divisor
. Also use all caps for meta-syntactic
variables, such as when you show the decomposition of a list or
vector into subunits, some of which may vary.
- When a documentation string refers to a Lisp symbol, write it
as it would be printed (which usually means in lower case), with
single-quotes around it. For example: ``lambda''.
There are two exceptions: write
t
and nil
without single-quotes. Help mode automatically creates a hyperlink
when a documentation string uses a symbol name inside single
quotes, if the symbol has either a function or a variable
definition. You do not need to do anything special to make use of
this feature. However, when a symbol has both a function definition
and a variable definition, and you want to refer to just one of
them, you can specify which one by writing one of the words
`variable', `option',
`function', or `command', immediately
before the symbol name. (Case makes no difference in recognizing
these indicator words.) For example, if you write
This function sets the variable `buffer-file-name'.
then the hyperlink will refer only to the variable documentation of
buffer-file-name
, and not to its function
documentation. If a symbol has a function definition and/or a
variable definition, but those are irrelevant to the use of the
symbol that you are documenting, you can write the word
`symbol' before the symbol name to prevent making any
hyperlink. For example,
If the argument KIND-OF-RESULT is the symbol `list',
this function returns a list of all the objects
that satisfy the criterion.
does not make a hyperlink to the documentation, irrelevant here, of
the function list
.
- Don't write key sequences directly in documentation strings.
Instead, use the `\\[...]' construct to stand for
them. For example, instead of writing `C-f', write the
construct `\\[forward-char]'. When Emacs displays the
documentation string, it substitutes whatever key is currently
bound to
forward-char
. (This is normally
`C-f', but it may be some other character if the user
has moved key bindings.) See section .
- In documentation strings for a major mode, you will want to
refer to the key bindings of that mode's local map, rather than
global ones. Therefore, use the construct
`\\<...>' once in the documentation string to
specify which key map to use. Do this before the first use of
`\\[...]'. The text inside the
`\\<...>' should be the name of the variable
containing the local keymap for the major mode. It is not practical
to use `\\[...]' very many times, because display of
the documentation string will become slow. So use this to describe
the most important commands in your major mode, and then use
`\\{...}' to display the rest of the mode's
keymap.
top next prev
42.4. Tips on
Writing Comments
We recommend these conventions for where to put comments and how
to indent them:
- top`;'
- 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
- top`;;'
- 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)))
Every function that has no documentation string (presumably one
that is used 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.
- top`;;;'
- Comments that start with three semicolons, `;;;',
should start at the left margin. Such comments are used outside
function definitions to make general statements explaining the
design principles of the program. For example:
;;; This Lisp code is run in Emacs
;;; 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))
- top`;;;;'
- 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.
top prev
42.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. First, an
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:
- top`Author'
- 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>
- top`Maintainer'
- 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.
- top`Created'
- This optional line gives the original creation date of the
file. For historical interest only.
- top`Version'
- If you wish to record version numbers for the individual Lisp
program, put them in this line.
- top`Adapted-By'
- 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).
- top`Keywords'
- 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. Here is a table of them:
- top`;;; 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.
- top`;;; Documentation'
- This has been used in some files in place of `;;;
Commentary:', but `;;; Commentary:' is
preferred.
- top`;;; Change Log:'
- This begins change log information stored in the library file
(if you store the change history there). For most of the Lisp files
distributed with Emacs, the change history is kept in the file
`ChangeLog' and not in the source file at all; these files
do not have a `;;; Change Log:' line.
- top`;;; Code:'
- This begins the actual code of the program.
- top`;;; 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.
Next: Previous: