24.3.1 Conventions for Writing Minor Modes

There are conventions for writing minor modes just as there are for major modes (see Major Modes). These conventions are described below. The easiest way to follow them is to use the macro define-minor-mode. See Defining Minor Modes.

In addition, several major mode conventions (see Major Mode Conventions) apply to minor modes as well: those regarding the names of global symbols, the use of a hook at the end of the initialization function, and the use of keymaps and other tables.

The minor mode should, if possible, support enabling and disabling via Custom (see Customization Settings). To do this, the mode variable should be defined with defcustom, usually with :type 'boolean. If just setting the variable is not sufficient to enable the mode, you should also specify a :set method which enables the mode by invoking the mode command. Note in the variable’s documentation string that setting the variable other than via Custom may not take effect. Also, mark the definition with an autoload cookie (see autoload cookie), and specify a :require so that customizing the variable will load the library that defines the mode. For example:

(defcustom msb-mode nil
  "Toggle msb-mode.
Setting this variable directly does not take effect;
use either \\[customize] or the function `msb-mode'."
  :set 'custom-set-minor-mode
  :initialize 'custom-initialize-default
  :version "20.4"
  :type    'boolean
  :group   'msb
  :require 'msb)