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 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 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 lexical-binding
if it doesn’t already. See Using Lexical Binding.
provide
at the end of each separate Lisp file.
See Features.
require
to make sure they are loaded.
See Features.
(eval-when-compile (require 'bar))
This tells Emacs to load bar just before byte-compiling
foo, so that the macro definition is available during
compilation. Using 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.
cl-lib
library
rather than the old cl
library. The latter library is
deprecated and will be removed in a future version of Emacs.
framep
and 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 is-foo
.
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))
eval-after-load
and with-eval-after-load
in
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 file
,
file-name
, or 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.