@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
-@node Tips, GNU Emacs Internals, Antinews, Top
+@node Tips, GNU Emacs Internals, GPL, Top
@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
@itemize @bullet
@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. Then take care to begin the
-names of all global variables, constants, and functions with the chosen
+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
+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
+variables, constants, and functions in your program with the chosen
prefix. This helps avoid name conflicts.
This recommendation applies even to names for traditional Lisp
@cindex reserved keys
@cindex keys, reserved
Please do not define @kbd{C-c @var{letter}} as a key in your major
-modes. These sequences are reserved for users; they are the
-@strong{only} sequences reserved for users, so do not block them.
+modes. Sequences consisting of @kbd{C-c} and a letter (either upper
+or lower case) are reserved for users; they are the @strong{only}
+sequences reserved for users, so do not block them.
-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 Emacs major modes to respect this convention was a
+lot of work; abandoning this convention would make that work go to
+waste, and inconvenience users. Please comply with it.
-Changing all the Emacs major modes to follow this 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 a control character or a
+digit are reserved for major modes.
@item
Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
users.
@item
+@cindex mouse-2
+@cindex references, following
Special major modes used for read-only text should usually redefine
@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
Modes such as Dired, Info, Compilation, and Occur redefine it in this
@item
When a package provides a modification of ordinary Emacs behavior, it is
-good to include a command to enable and disable the feature, Provide a
+good to include a command to enable and disable the feature, provide a
command named @code{@var{whatever}-mode} which turns the feature on or
off, and make it autoload (@pxref{Autoload}). Design the package so
that simply loading it has no visible effect---that should not enable
-the feature. Users will request the feature by invoking the command.
+the feature.@footnote{Consider that the package may be loaded
+arbitrarily by Custom for instance.} Users will request the feature by
+invoking the command.
@item
It is a bad idea to define aliases for the Emacs primitives. Use the
standard names instead.
+@item
+If a package needs to define an alias or a new function for
+compatibility with some other version of Emacs, name it with the package
+prefix, not with the raw name with which it occurs in the other version.
+Here is an example from Gnus, which provides many examples of such
+compatibility issues.
+
+@example
+(defalias 'gnus-point-at-bol
+ (if (fboundp 'point-at-bol)
+ 'point-at-bol
+ 'line-beginning-position))
+@end example
+
@item
Redefining (or advising) an Emacs primitive is discouraged. It may do
the right thing for a particular program, but there is no telling what
An error message should start with a capital letter but should not end
with a period.
+@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
+region or position arguments. Instead, provide @code{nil} for those
+arguments if they were not specified, and have the function body
+compute the default value when the argument is @code{nil}. For
+instance, write this:
+
+@example
+(defun foo (pos)
+ (interactive
+ (list (if @var{specified} @var{specified-pos})))
+ (unless pos (setq pos @var{default-pos}))
+ ...)
+@end example
+
+@noindent
+rather than this:
+
+@example
+(defun foo (pos)
+ (interactive
+ (list (if @var{specified} @var{specified-pos}
+ @var{default-pos})))
+ ...)
+@end example
+
+@noindent
+This is so that repetition of the command will recompute
+these defaults based on the current circumstances.
+
+You do not need to take such precautions when you use interactive
+specs @samp{d}, @samp{m} and @samp{r}, because they make special
+arrangements to recompute the argument values on repetition of the
+command.
+
@item
Many commands that take a long time to execute display a message that
-says @samp{Operating...} when they start, and change it to
+says something like @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.
+@emph{no} period after @samp{done}.
@item
Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
@item
@cindex profiling
@cindex timing programs
-@cindex @file{profile.el}
@cindex @file{elp.el}
-Profile your program with the @file{profile} library or the @file{elp}
-library. See the files @file{profile.el} and @file{elp.el} for
-instructions.
+Profile your program with the @file{elp} library. See the file
+@file{elp.el} for instructions.
@item
Use iteration rather than recursion whenever possible.
longer the case---documentation strings now take up very little space in
a running Emacs.
+@item
+Format the documentation string so that it fits in an Emacs window on an
+80-column screen. It is a good idea for most lines to be no wider than
+60 characters. The first line should not be wider than 67 characters
+or it will look bad in the output of @code{apropos}.
+
+You can fill the text if that looks good. However, rather than blindly
+filling the entire documentation string, you can often make it much more
+readable by choosing certain line breaks with care. Use blank lines
+between topics if the documentation string is long.
+
@item
The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary. @kbd{M-x
stand on their own, the result looks bad. In particular, start the
first line with a capital letter and end with a period.
-The documentation string is not limited to one line; use as many lines
-as you need to explain the details of how to use the function or
-variable. Please use complete sentences in the additional lines.
+For a function, the first line should briefly answer the question,
+``What does this function do?'' For a variable, the first line should
+briefly answer the question, ``What does this value mean?''
+
+Don't limit the documentation string to one line; use as many lines as
+you need to explain the details of how to use the function or
+variable. Please use complete sentences for the rest of the text too.
@item
For consistency, phrase the verb in the first sentence of a function's
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.
+is indicative and has a proper subject.
@item
Write documentation strings in the active voice, not the passive, and in
@item
Do not start or end a documentation string with whitespace.
-
-@item
-Format the documentation string so that it fits in an Emacs window on an
-80-column screen. It is a good idea for most lines to be no wider than
-60 characters. The first line should not be wider than 67 characters
-or it will look bad in the output of @code{apropos}.
-
-You can fill the text if that looks good. However, rather than blindly
-filling the entire documentation string, you can often make it much more
-readable by choosing certain line breaks with care. Use blank lines
-between topics if the documentation string is long.
@item
@strong{Do not} indent subsequent lines of a documentation string so
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
+distracting.
+
@item
When a function's documentation string mentions the value of an argument
of the function, use the argument name in capital letters as if it were
have the form (KEY . VALUE). Here, KEY is ...
@end example
+@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
+``Foo'' (which is a different symbol).
+
+This might appear to contradict the policy of writing function
+argument values, but there is no real contradiction; the argument
+@emph{value} is not the same thing as the @emph{symbol} which the
+function uses to hold the value.
+
+If this puts a lower-case letter at the beginning of a sentence
+and that annoys you, rewrite the sentence so that the symbol
+is not at the start of it.
+
@item
If a line in a documentation string begins with an open-parenthesis,
write a backslash before the open-parenthesis, like this:
HCoop / bpt / emacs.git / blobdiff