@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, Calendar, Top
-@appendix Tips and Standards
+@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
@cindex coding standards
- This chapter describes no additional features of Emacs Lisp.
-Instead it gives advice on making effective use of the features described
-in the previous chapters.
+ This chapter describes no additional features of Emacs Lisp. Instead
+it gives advice on making effective use of the features described in the
+previous chapters, and describes conventions Emacs Lisp programmers
+should follow.
@menu
-* Style Tips:: Writing clean and robust programs.
+* Coding Conventions:: Conventions for clean and robust programs.
* Compilation Tips:: Making compiled code run fast.
* Documentation Tips:: Writing readable documentation strings.
* Comment Tips:: Conventions for writing comments.
* Library Headers:: Standard headers for library packages.
@end menu
-@node Style Tips
-@section Writing Clean Lisp Programs
+@node Coding Conventions
+@section Emacs Lisp Coding Conventions
- Here are some tips for avoiding common errors in writing Lisp code
-intended for widespread use:
+ Here are conventions that you should follow when writing Emacs Lisp
+code intended for widespread use:
@itemize @bullet
@item
library program, at least if there is more than one entry point to the
program.
+@item
+If a file requires certain other library programs to be loaded
+beforehand, then the comments at the beginning of the file should say
+so. Also, use @code{require} to make sure they are loaded.
+
@item
If one file @var{foo} uses a macro defined in another file @var{bar},
-@var{foo} should contain @code{(require '@var{bar})} before the first
-use of the macro. (And @var{bar} should contain @code{(provide
-'@var{bar})}, to make the @code{require} work.) This will cause
-@var{bar} to be loaded when you byte-compile @var{foo}. Otherwise, you
-risk compiling @var{foo} without the necessary macro loaded, and that
-would produce compiled code that won't work right. @xref{Compiling
-Macros}.
+@var{foo} should contain this expression before the first use of the
+macro:
+
+@example
+(eval-when-compile (require '@var{bar}))
+@end example
+
+@noindent
+(And @var{bar} should contain @code{(provide '@var{bar})}, to make the
+@code{require} work.) This will cause @var{bar} to be loaded when you
+byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without
+the necessary macro loaded, and that would produce compiled code that
+won't work right. @xref{Compiling Macros}.
+
+Using @code{eval-when-compile} avoids loading @var{bar} when
+the compiled version of @var{foo} is @emph{used}.
+
+@item
+When defining a major mode, please follow the major mode
+conventions. @xref{Major Mode Conventions}.
@item
-If you define a major mode, make sure to run a hook variable using
-@code{run-hooks}, just as the existing major modes do. @xref{Hooks}.
+When defining a minor mode, please follow the minor mode
+conventions. @xref{Minor Mode Conventions}.
@item
If the purpose of a function is to tell you whether a certain condition
@strong{only} sequences reserved for users, so we cannot do without
them.
-Instead, define sequences consisting of @kbd{C-c} followed by a
-non-letter. These sequences are reserved for major modes.
+Instead, define sequences consisting of @kbd{C-c} followed by a control
+character, a digit, or certain punctuation characters. These sequences
+are reserved for major modes.
Changing all the major modes in Emacs 18 so they would follow this
-convention was a lot of work. Abandoning this convention would waste
-that work and inconvenience the users.
+convention was a lot of work. Abandoning this convention would make
+that work go to waste, and inconvenience users.
+
+@item
+Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
+@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
+
+@item
+Sequences consisting of @kbd{C-c} followed by any other punctuation
+character are allocated for minor modes. Using them in a major mode is
+not absolutely prohibited, but if you do that, the major mode binding
+may be shadowed from time to time by minor modes.
@item
You should not bind @kbd{C-h} following any prefix character (including
standard names instead.
@item
-Redefining an Emacs primitive is an even worse idea.
-It may do the right thing for a particular program, but
-there is no telling what other programs might break as a result.
+Redefining (or advising) an Emacs primitive is discouraged. It may do
+the right thing for a particular program, but there is no telling what
+other programs might break as a result.
@item
If a file does replace any of the functions or library programs of
say which functions are replaced, and how the behavior of the
replacements differs from that of the originals.
-@item
-If a file requires certain standard library programs to be loaded
-beforehand, then the comments at the beginning of the file should say
-so.
-
@item
Please keep the names of your Emacs Lisp source files to 13 characters
or less. This way, if the files are compiled, the compiled files' names
Do not use @code{message}, @code{throw}, @code{sleep-for},
or @code{beep} to report errors.
+@item
+An error message should start with a capital letter but should not end
+with a period.
+
+@item
+Many commands that take a long time to execute display a message that
+says @samp{Operating...} when they start, and change it to
+@samp{Operating...done} when they finish. Please keep the style of
+these messages uniform: @emph{no} space around the ellipsis, and
+@emph{no} period at the end.
+
@item
Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
command does: use a new local keymap that contains one command defined
only for program-generated buffers.) The users will find Emacs more
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.
+
+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 variables names.
+Therefore, you should rename the 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
default indentation parameters.
is calling another compiled function.
@item
-Using the primitive list-searching functions @code{memq}, @code{assq}, or
-@code{assoc} is even faster than explicit iteration. It may be worth
-rearranging a data structure so that one of these primitive search
-functions can be used.
+Using the primitive list-searching functions @code{memq}, @code{member},
+@code{assq}, or @code{assoc} is even faster than explicit iteration. It
+may be worth rearranging a data structure so that one of these primitive
+search functions can be used.
@item
Certain built-in functions are handled specially in byte-compiled code,
view the documentation. Remember that the indentation before the
starting double-quote is not part of the string!
+@item
+When the user tries to use a disabled command, Emacs displays just the
+first paragraph of its documentation string---everything through the
+first blank line. If you wish, you can choose which information to
+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
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
-instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When
-Emacs displays the documentation string, it substitutes whatever key is
-currently bound to @code{forward-char}. (This is normally @samp{C-f},
-but it may be some other character if the user has moved key bindings.)
-@xref{Keys in Documentation}.
+instead of writing @samp{C-f}, write the construct
+@samp{\\[forward-char]}. When Emacs displays the documentation string,
+it substitutes whatever key is currently bound to @code{forward-char}.
+(This is normally @samp{C-f}, but it may be some other character if the
+user has moved key bindings.) @xref{Keys in Documentation}.
@item
In documentation strings for a major mode, you will want to refer to the
display of the documentation string will become slow. So use this to
describe the most important commands in your major mode, and then use
@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
-
-@item
-Don't use the term ``Elisp'', since that is or was a trademark.
-Use the term ``Emacs Lisp''.
@end itemize
@node Comment Tips