* doc/lispref/loading.texi (When to Autoload): New section.

1 files changed, 40 insertions, 0 deletions

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index d925c8c8f65..80dcb488983 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -468,6 +468,10 @@ runs the real definition as if it had been loaded all along.
 Autoloading can also be triggered by looking up the documentation of
 the function or macro (@pxref{Documentation Basics}).
 
+@menu
+* When to Autoload::   When to Use Autoload.
+@end menu
+
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a ``magic'' comment in the
 source before the real definition.  @code{autoload} is the low-level
@@ -699,6 +703,42 @@ symbol's new function value.  If the value of the optional argument
 function, only a macro.
 @end defun
 
+@node When to Autoload
+@subsection When to Use Autoload
+@cindex autoload, when to use
+
+Do not add an autoload comment unless it is really necessary.
+Autoloading code means it is always globally visible.  Once an item is
+autoloaded, there is no compatible way to transition back to it not
+being autoloaded (after people become accustomed to being able to use it
+without an explicit load).
+
+@itemize
+@item
+The most common items to autoload are the interactive entry points to a
+library.  For example, if @file{python.el} is a library defining a
+major-mode for editing Python code, autoload the definition of the
+@code{python-mode} function, so that people can simply use @kbd{M-x
+python-mode} to load the library.
+
+@item
+Variables usually don't need to be autoloaded.  An exception is if the
+variable on its own is generally useful without the whole defining
+library being loaded.  (An example of this might be something like
+@code{find-exec-terminator}.)
+
+@item
+Don't autoload a user option just so that a user can set it.
+
+@item
+Never add an autoload @emph{comment} to silence a compiler warning in
+another file.  In the file that produces the warning, use
+@code{(defvar foo)} to silence an undefined variable warning, and
+@code{declare-function} (@pxref{Declaring Functions}) to silence an
+undefined function warning; or require the relevant library; or use an
+explicit autoload @emph{statement}.
+@end itemize
+
 @node Repeated Loading
 @section Repeated Loading
 @cindex repeated loading