DataMuseum.dk

top - metrics - download

    Length: 5195 (0x144b)
    Types: TextFile
    Names: »tips.texinfo«

└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
    └─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z« 
        └─⟦1b57a2ffe⟧ 
            └─⟦this⟧ »tips.texinfo« 

TextFile

@setfilename ../info/tips
@node Tips and Standards, GNU Emacs Internals, Emacs Display, Top
@chapter Tips and Standards for Emacs Lisp programs

Here are some tips for avoiding common errors in writing Lisp code
for other people to use:

@itemize @bullet
@item
Since all global names are in the same name space, you should take care to
prefix the names of all global variables, constants, and functions with the
major mode name (or with an abbreviation of it if the name is long).
This helps avoid name conflicts.

This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp---even to @code{cadr}!
Believe it or not, there is more than one plausible way to define
@code{cadr}.  Play it safe; append your name prefix to produce a name
like @code{foo-cadr} or @code{mylib-cadr} instead.

If one prefix is insufficient, your package may use two or three
alternative common words, so long as they make sense.

@item
Please do not define @kbd{C-c @var{letter}} as a key.  These sequences
are reserved for users; they are the @strong{only} sequences reserved
for users, so we cannot do without them.

Everything in Emacs that used to define such sequences has been changed,
which was a lot of work.  Abandoning this convention would waste that
work, and hurt the users.

@item
It is a bad idea to define aliases for the Emacs primitives.
Use the standard names instead.

@item
Every command, function or variable intended for users to know about
should have a documention string.

@item
The first line of the documentation string should consist of one or two
complete sentences which stand on their own as a summary.  In particular,
start with a capital letter and end with a period.

A doc string can have additional lines which expand on the details of
how to use the function or variable.  The additional lines should be
made up of complete sentences also, but they may be filled if that
looks good.

@item
@strong{Do not} indent subsequent lines of doc string so that their text
is lined up with the text of the first line.  This looks nice in the
source code, but looks bad when users view the documentation.  Remember
that the indentation before the starting doublequote is not part of the
string!

@item
A variable's doc string should start with @samp{*} if the variable is one
that users would want to set interactively often.  If the value is a long
list, or a function, or the variable would only be set in init files,
then don't start the doc string with @samp{*}.

@item
In documentation strings, don't write key sequences directly.
Instead, use the @samp{\\[@dots{}]} construct to stand for them.
For example, instead of writing @samp{C-f}, write @samp{\\[forward-char]}.
When the doc string is printed, Emacs will replace it
with whatever key runs @code{forward-char}.  This will usually be @samp{C-f},
but if the user has moved key bindings, it will be the correct
key for that user.

In doc strings for a major mode, do the same thing.  However, you will
want to refer to the key bindings of that mode's local map, rather than
global ones.  Therefore, use the construct @samp{\\<@dots{}>} once in
the doc string to specify which key map to use.  Do this before the
first use of @samp{\\[@dots{}]}.  The text inside the @samp{\\<@dots{}>}
should be the name of the variable containing the local keymap for that
major mode.

@item
Don't use @code{next-line} or @code{previous-line} in programs; nearly
always, @code{forward-line} is more convenient as well as more
predictable and robust.

@item
Don't use functions that set the mark in your Lisp code
(unless you are writing a command to set the mark).
The mark is for the user to use, and messing it up is incorrect.

In particular, don't use these functions:

@itemize @bullet
@item
@code{beginning-of-buffer}, @code{end-of-buffer}
@item
@code{replace-string}, @code{replace-regexp}
@end itemize

If you just want to move point, or just replace a certain string,
without any of the other features intended for interactive users,
you can replace these with one or two lines of simple Lisp code.

@item
The recommended way to print a message in the echo area is with
the @code{message} function, not @code{princ}.

@item
When you encounter an error condition, call the function @code{error}.
This function does not return.

Do not use @code{message}, @code{throw}, @code{sleep-for},
or @code{beep} to report errors.

@item
Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
default indentation parameters.  Or @kbd{M-C-\} (@code{indent-region}).

@item
Avoid using recursive edits.  Instead, do what the Rmail @kbd{w} command
does: use a new local keymap which contains one command defined to
switch back to the old local keymap.  Or do what the @code{edit-options}
command does: switch to another buffer and let the user switch back at
will.

@item
Please put a copyright notice on the file if you give copies to anyone.
Use the same lines that appear at the top of the Lisp files in Emacs
itself.  If you have not signed papers to assign the copyright to the
Foundation, then place your name in the copyright notice in place of the
Foundation's name.
@end itemize