@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
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
@item
Try to avoid compiler warnings about undefined free variables, by adding
-@cdode{defvar} definitions for these variables.
+@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
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