12.6 Tips for Defining Variables Robustly

When you define a variable whose value is a function, or a list of functions, use a name that ends in ‘-function’ or ‘-functions’, respectively.

There are several other variable name conventions; here is a complete list:

…-hook

The variable is a normal hook (see Hooks).

…-function

The value is a function.

…-functions

The value is a list of functions.

…-form

The value is a form (an expression).

…-forms

The value is a list of forms (expressions).

…-predicate

The value is a predicate—a function of one argument that returns non-nil for success and nil for failure.

…-flag

The value is significant only as to whether it is nil or not. Since such variables often end up acquiring more values over time, this convention is not strongly recommended.

…-program

The value is a program name.

…-command

The value is a whole shell command.

…-switches

The value specifies options for a command.

prefix--…

The variable is intended for internal use and is defined in the file prefix.el. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.)

…-internal

The variable is intended for internal use and is defined in C code. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.)

When you define a variable, always consider whether you should mark it as safe or risky; see File Local Variables.

When defining and initializing a variable that holds a complicated value (such as a syntax table for a major mode), it’s best to put the entire computation of the value into the defvar, like this:

(defvar my-major-mode-syntax-table
  (let ((table (make-syntax-table)))
    (modify-syntax-entry ?# "<" table)
    …
    table)
  docstring)

This method has several benefits. First, if the user quits while loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is important if the user has changed its value. Third, evaluating the defvar form with C-M-x will reinitialize the variable completely.