@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
-@node Tips, GNU Emacs Internals, System Interface, Top
+@node Tips, GNU Emacs Internals, Antinews, Top
@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
previous chapters, and describes conventions Emacs Lisp programmers
should follow.
+ You can automatically check some of the conventions described below by
+running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
+It cannot check all of the conventions, and not all the warnings it
+gives necessarily correspond to problems, but it is worth examining them
+all.
+
@menu
* Coding Conventions:: Conventions for clean and robust programs.
* Compilation Tips:: Making compiled code run fast.
Using @code{eval-when-compile} avoids loading @var{bar} when
the compiled version of @var{foo} is @emph{used}.
+@item
+Please don't require the @code{cl} package of Common Lisp extensions at
+run time. Use of this package is optional, and it is not part of the
+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, for the sake of macros. You do that like this:
+
+@example
+(eval-when-compile (require 'cl))
+@end example
+
@item
When defining a major mode, please follow the major mode
conventions. @xref{Major Mode Conventions}.
@item
Anything which acts like a temporary mode or state which the user can
-enter and leave should define @kbd{@key{ESC} @key{ESC}} of
+enter and leave should define @kbd{@key{ESC} @key{ESC}} or
@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
For a state which accepts ordinary Emacs commands, or more generally any
Try to avoid compiler warnings about undefined free variables, by adding
@code{defvar} definitions for these variables.
+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
+(eval-when-compile
+ (require 'foo)
+ (defvar bar-baz))
+@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,
that looks good.
@item
-For consistency, phrase the verb in the first sentence of a
-function's documentation string as an infinitive with ``to'' omitted. For
-instance, use ``Return the cons of A and B.'' in preference to ``Returns
-the cons of A and B@.'' Usually it looks good to do likewise for the
-rest of the first paragraph. Subsequent paragraphs usually look better
-if they have proper subjects.
+For consistency, phrase the verb in the first sentence of a function's
+documentation string as an imperative--for instance, use ``Return the
+cons of A and B.'' in preference to ``Returns the cons of A and B@.''
+Usually it looks good to do likewise for the rest of the first
+paragraph. Subsequent paragraphs usually look better if each sentence
+has a proper subject.
@item
Write documentation strings in the active voice, not the passive, and in
@code{/} refers to its second argument as @samp{DIVISOR}, because the
actual argument name is @code{divisor}.
-Also use all caps for meta-syntactic variables, such as when you show
+Also use all caps for metasyntactic variables, such as when you show
the decomposition of a list or vector into subunits, some of which may
-vary.
+vary. @samp{KEY} and @samp{VALUE} in the following example
+illustrate this practice:
+
+@example
+The argument TABLE should be an alist whose elements
+have the form (KEY . VALUE). Here, KEY is ...
+@end example
@item
@iftex
does not make a hyperlink to the documentation, irrelevant here, of the
function @code{list}.
+To make a hyperlink to Info documentation, write the name of the Info
+node in single quotes, preceded by @samp{info node} or @samp{Info
+node}. The Info file name defaults to @samp{emacs}. For example,
+
+@smallexample
+See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+@end smallexample
+
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
Emacs has conventions for using special comments in Lisp libraries
to divide them into sections and give information such as who wrote
-them. This section explains these conventions. First, an example:
+them. This section explains these conventions.
+
+ We'll start with an example, a package that is included in the Emacs
+distribution.
+
+ Parts of this example reflect its status as part of Emacs; for
+example, the copyright notice lists the Free Software Foundation as the
+copyright holder, and the copying permission says the file is part of
+Emacs. When you write a package and post it, the copyright holder would
+be you (unless your employer claims to own it instead), and you should
+get the suggested copying permission from the end of the GNU General
+Public License itself. Don't say your file is part of Emacs
+if we haven't installed it in Emacs yet!
+
+ With that warning out of the way, on to the example:
@smallexample
@group
store the change history there). For most of the Lisp
files distributed with Emacs, the change history is kept in the file
@file{ChangeLog} and not in the source file at all; these files do
-not have a @samp{;;; Change Log:} line.
+not have a @samp{;;; Change Log:} line. @samp{History} is an
+alternative to @samp{Change Log}.
@item ;;; Code:
This begins the actual code of the program.
HCoop / bpt / emacs.git / blobdiff