(Coding Conventions): Separate defvar and require

methods to avoid warnings.  Use require only when there are many
functions and variables from that package.

1 files changed, 22 insertions, 13 deletions

diff --git a/lispref/tips.texi b/lispref/tips.texi
index a85147f1d8f..4182260028b 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -370,25 +370,34 @@ coherent if all libraries use the same conventions.
 
 @item
 Try to avoid compiler warnings about undefined free variables, by adding
-@code{defvar} definitions for these variables.
+dummy @code{defvar} definitions for these variables, like this:
 
-Sometimes adding a @code{require} for another package is useful to avoid
-compilation warnings for variables and functions defined in that
-package.  If you do this, often it is better if the @code{require} acts
-only at compile time.  Here's how to do that:
+@example
+(defvar foo)
+@end example
+
+Such a definition has no effect except to tell the compiler
+not to warn about uses of the variable @code{foo} in this file.
+
+@item
+If you use many functions and variables from a certain file, you can
+add a @code{require} for that package to avoid compilation warnings
+for them.  It is better if the @code{require} acts only at compile
+time.  Here's how to do this:
 
 @example
 (eval-when-compile
-  (require 'foo)
-  (defvar bar-baz))
+  (require 'foo))
 @end example
 
-If you bind a variable in one function, and use it or set it in another
-function, the compiler warns about the latter function unless the
-variable has a definition.  But often these variables have short names,
-and it is not clean for Lisp packages to define such variable names.
-Therefore, you should rename the variable to start with the name prefix
-used for the other functions and variables in your package.
+@item
+If you bind a variable in one function, and use it or set it in
+another function, the compiler warns about the latter function unless
+the variable has a definition.  But adding a definition would be
+unclean if the variable has a short names, since Lisp packages should
+not define short variable names.  The right thing to do is to rename
+this variable to start with the name prefix used for the other
+functions and variables in your package.
 
 @item
 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the