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 ‘defun’ or ‘defvar’, 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 ‘email@example.com’ 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.
provideat the end of each separate Lisp file. See Named Features.
requireto make sure they are loaded. See Named 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
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 Compiling Macros.
requirethat 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
requirestatements inside the relevant functions rather than at the top-level. Or use
autoloadstatements 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-liblibrary rather than the old
cllibrary. The latter does not use a clean namespace (i.e., its definitions do not start with a ‘cl-’ prefix). If your package loads
clat run time, that could cause name clashes for users who don’t use that package.
There is no problem with using the
cl package at compile
(eval-when-compile (require 'cl)). That’s
sufficient for using the macros in the
cl package, because the
compiler expands them before generating the byte-code. It is still
better to use the more modern
cl-lib in this case, though.
frame-live-p. We recommend to avoid using this
-psuffix in boolean variable names, unless the variable is bound to a predicate function; instead, use a
-flagsuffix or names like
feature-unload-function, where feature is the name of the feature the package provides, and make it undo any such changes. Using
unload-featureto unload the file will run this function. See Unloading.
(defalias 'gnus-point-at-bol (if (fboundp 'point-at-bol) 'point-at-bol 'line-beginning-position))
with-eval-after-loadin 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.
The benefits of a Common Lisp-style package system are considered not to outweigh the costs.