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-bindingin new code, and converting existing Emacs Lisp code to enable
lexical-bindingif it doesn’t already. See Using Lexical Binding.
provideat the end of each separate Lisp file. See Features.
requireto 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
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.
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 library is deprecated and will be removed in a future version of Emacs.
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
unload-featurewill 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-featurewill 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))
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.
pathin its name, preferring
directoryinstead, 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.