@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005 Free Software Foundation, Inc.
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, GPL, Top
@node Coding Conventions
@section Emacs Lisp Coding Conventions
+@cindex coding conventions in Emacs Lisp
Here are conventions that you should follow when writing Emacs Lisp
code intended for widespread use:
@item
Since all global variables share the same name space, and all
functions share another name space, you should choose a short word to
-distinguish your program from other Lisp programs.@footnote{The
+distinguish your program from other Lisp programs@footnote{The
benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.} Then take care to begin the names of all global
+outweigh the costs.}. Then take care to begin the names of all global
variables, constants, and functions in your program with the chosen
prefix. This helps avoid name conflicts.
+Occasionally, for a command name intended for users to use, it is more
+convenient if some words come before the package's name prefix. And
+constructs that define functions, variables, etc., work better if they
+start with @samp{defun} or @samp{defvar}, so put the name prefix later
+on in the name.
+
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp---such as
@code{copy-list}. Believe it or not, there is more than one plausible
standard Emacs namespace. If your package loads @code{cl} at run time,
that could cause name clashes for users who don't use that package.
-However, there is no problem with using the @code{cl} package at compile
-time, with @code{(eval-when-compile (require 'cl))}.
+However, there is no problem with using the @code{cl} package at
+compile time, with @code{(eval-when-compile (require 'cl))}. That's
+sufficient for using the macros in the @code{cl} package, because the
+compiler expands them before generating the byte-code.
@item
When defining a major mode, please follow the major mode
@end example
@item
-Redefining (or advising) an Emacs primitive is discouraged. It may do
+Redefining (or advising) an Emacs primitive is a bad idea. It may do
the right thing for a particular program, but there is no telling what
-other programs might break as a result.
+other programs might break as a result. In any case, it is a problem
+for debugging, because the advised function doesn't do what its source
+code says it does. If the programmer investigating the problem is
+unaware that there is advice on the function, the experience can be
+very frustrating.
+
+We hope to remove all the places in Emacs that advise primitives.
+In the mean time, please don't add any more.
+
+@item
+It is likewise a bad idea for one Lisp package to advise a function
+in another Lisp package.
+
+@item
+Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
+Loading}) in libraries and packages. This feature is meant for
+personal customizations; using it in a Lisp program is unclean,
+because it modifies the behavior of another Lisp file in a way that's
+not visible in that file. This is an obstacle for debugging, much
+like advising a function in the other package.
@item
If a file does replace any of the functions or library programs of
replacements differs from that of the originals.
@item
-Avoid using macros that define functions and variables with names that
-are constructed. It is best for maintenance when the name of the
-function or variable being defined is given explicitly in the source
-code, as the second element of the list---as it is when you use
-@code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}.
+Constructs that define a function or variable should be macros,
+not functions, and their names should start with @samp{def}.
+
+@item
+Macros that define a functions or variables should take the name to be
+defined as the first argument. That will help various tools find the
+definition automatically. Avoid constructing the names in the macro
+itself, since that would confuse these tools.
@item
Please keep the names of your Emacs Lisp source files to 13 characters
only for special-purpose buffers.) The users will find Emacs more
coherent if all libraries use the same conventions.
+@item
+If your program contains non-ASCII characters in string or character
+constants, you should make sure Emacs always decodes these characters
+the same way, regardless of the user's settings. There are two ways
+to do that:
+
+@itemize -
+@item
+Use coding system @code{emacs-mule}, and specify that for
+@code{coding} in the @samp{-*-} line or the local variables list.
+
+@example
+;; XXX.el -*- coding: emacs-mule; -*-
+@end example
+
+@item
+Use one of the coding systems based on ISO 2022 (such as
+iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at
+the end for @code{coding}. (The @samp{!} turns off any possible
+character translation.)
+
+@example
+;; XXX.el -*- coding: iso-latin-2!; -*-
+@end example
+@end itemize
+
@item
Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
default indentation parameters.
;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
-;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
-;; MA 02110-1301 USA
+;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301 USA
@end smallexample
If you have signed papers to assign the copyright to the Foundation,
An error message should start with a capital letter but should not end
with a period.
+@item
+A question asked in the minibuffer with @code{y-or-n-p} or
+@code{yes-or-no-p} should start with a capital letter and end with
+@samp{? }.
+
+@item
+When you mention a default value in a minibuffer prompt,
+put it and the word @samp{default} inside parentheses.
+It should look like this:
+
+@example
+Enter the answer (default 42):
+@end example
+
@item
In @code{interactive}, if you use a Lisp expression to produce a list
of arguments, don't try to provide the ``correct'' default values for
include before the first blank line so as to make this display useful.
@item
-A variable's documentation string should start with @samp{*} if the
-variable is one that users would often want to set interactively. If
-the value is a long list, or a function, or if the variable would be set
-only in init files, then don't start the documentation string with
-@samp{*}. @xref{Defining Variables}.
+When you define a variable that users ought to set interactively, you
+normally should use @code{defcustom}. However, if for some reason you
+use @code{defvar} instead, start the doc string with a @samp{*}.
+@xref{Defining Variables}.
@item
The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means@dots{}'', to make it clear that
+start with words such as ``Non-nil means,'' to make it clear that
all non-@code{nil} values are equivalent and indicate explicitly what
@code{nil} and non-@code{nil} mean.
@item
The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if @dots{}'', to indicate
-explicitly what constitutes ``truth''. The word ``return'' avoids
-starting the sentence with lower-case ``t'', which is somewhat
+should start with words such as ``Return t if,'' to indicate
+explicitly what constitutes ``truth.'' The word ``return'' avoids
+starting the sentence with lower-case ``t,'' which could be somewhat
distracting.
@item
@item
Never change the case of a Lisp symbol when you mention it in a doc
-string. If the symbol's name is @code{foo}, write ``foo'', not
+string. If the symbol's name is @code{foo}, write ``foo,'' not
``Foo'' (which is a different symbol).
This might appear to contradict the policy of writing function
If a symbol has a function definition and/or a variable definition, but
those are irrelevant to the use of the symbol that you are documenting,
-you can write the word @samp{symbol} before the symbol name to prevent
-making any hyperlink. For example,
+you can write the words @samp{symbol} or @samp{program} before the
+symbol name to prevent making any hyperlink. For example,
@example
If the argument KIND-OF-RESULT is the symbol `list',
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
@end smallexample
+Finally, to create a hyperlink to URLs, write the URL in single
+quotes, preceded by @samp{URL}. For example,
+
+@smallexample
+The home page for the GNU project has more information (see URL
+`http://www.gnu.org/').
+@end smallexample
+
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,