Here are conventions that you should follow when writing Emacs Lisp code intended for widespread use:
This convention is mandatory for any file that includes custom definitions. If fixing such a file to follow this convention requires an incompatible change, go ahead and make the incompatible change; don’t postpone it.
Occasionally, for a command name intended for users to use, it is more convenient if some words come before the package’s name prefix. For example, it is our convention to have commands that list objects named as ‘list-something’, e.g., a package called ‘frob’ could have a command ‘list-frobs’, when its other global symbols begin with ‘frob-’. Also, constructs that define functions, variables, etc., work better if they start with ‘define-’, so put the name prefix later on in the name.
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp—such as
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
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 ‘firstname.lastname@example.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 can use two or three alternative common prefixes, so long as they make sense.
lexical-binding in new code, and
converting existing Emacs Lisp code to enable
if it doesn’t already. See Using Lexical Binding.
provide at the end of each separate Lisp file.
require to make sure they are loaded.
(eval-when-compile (require 'bar))
This tells Emacs to load bar just before byte-compiling
foo, so that the macro definition is available during
eval-when-compile avoids loading bar
when the compiled version of foo is used. It should be
called before the first use of the macro in the file. See Macros and Byte Compilation.
require that library at the top-level and be done
with it. But if your file contains several independent features, and
only one or two require the extra library, then consider putting
require statements inside the relevant functions rather than at
the top-level. Or use
autoload statements to load the extra
library when needed. This way people who don’t use those aspects of
your file do not need to load the extra library.
rather than the old
cl library. The latter library is
deprecated and will be removed in a future version of Emacs.
frame-live-p. We recommend to
avoid using this
-p suffix in boolean variable names, unless
the variable is bound to a predicate function; instead, use a
-flag suffix or names like
unload-feature will undo the changes usually done by
loading a feature (like adding functions to hooks). However, if
loading feature does something unusual and more complex, you can
define a function named
feature-unload-function, and make
it undo any such special changes.
unload-feature will then
automatically run this function if it exists. See Unloading.
(defalias 'gnus-point-at-bol (if (fboundp 'point-at-bol) 'point-at-bol 'line-beginning-position))
libraries and packages (see Hooks for Loading). This feature is
meant for personal customizations; using it in a Lisp program is
unclean, because it modifies the behavior of another Lisp file in a
way that’s not visible in that file. This is an obstacle for
debugging, much like advising a function in the other package.
path in its name, preferring
directory instead, since Emacs follows the
GNU convention to use the term path only for search paths,
which are lists of directory names.
The benefits of a Common Lisp-style package system are considered not to outweigh the costs.