@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
the compiled version of @var{foo} is @emph{used}.
@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 major mode, please follow the major mode
+conventions. @xref{Major Mode Conventions}.
+
+@item
+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 make
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
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.
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