This pages explains when to use defcustom, when to use defvar and when to use defconst.

Look at BufferLocalVariable for variables that have a different value in every buffer (such as ‘buffer-file-name’).

Use ‘defcustom’.
If the variable is only used by code, use ‘defvar’.
Use ‘defconst’. Note this doesn’t prevent changing the variable, it just makes the author’s intention explicit.
From the EmacsManual :
C-M-x (eval-defun) treats ‘defvar’ expressions specially. Normally, evaluating a ‘defvar’ expression does nothing if the variable it defines already has a value. But C-M-x unconditionally resets the variable to the initial value specified in the ‘defvar’ expression. ‘defcustom’ expressions are treated similarly. This special feature is convenient for debugging Lisp programs.

Prior to version 24.3 of GNU Emacs, variables with DocStrings that start with an asterisk were considered possible candidates for ‘M-x set-variable’. From GNU Emacs 24.3 on, docstrings starting with ‘*’ no longer indicate user options. Only variables defined using ‘defcustom’ are considered user options. – XueFuqiao

For more recent Emacs, this would be considered a bug for code distributed by GnuEmacs: Bug#23392 - Somebody should clean up the "*" in doc strings. It is not a bug for user code and 3rd-party libraries that are designed to work with older Emacs versions.

See also NonNilValues.

CategoryCode CategoryCustomize