[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes no additional features of XEmacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters.
A.1 Writing Clean Lisp Programs | Writing clean and robust programs. | |
A.2 Tips for Making Compiled Code Fast | Making compiled code run fast. | |
A.3 Tips for Documentation Strings | Writing readable documentation strings. | |
A.4 Tips on Writing Comments | Conventions for writing comments. | |
A.5 Conventional Headers for XEmacs Libraries | Standard headers for library packages. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some tips for avoiding common errors in writing Lisp code intended for widespread use:
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in XEmacs Lisp—even to cadr
.
Believe it or not, there is more than one plausible way to define
cadr
. Play it safe; append your name prefix to produce a name
like foo-cadr
or mylib-cadr
instead.
If you write a function that you think ought to be added to Emacs under
a certain name, such as twiddle-files
, don’t call it by that name
in your program. Call it mylib-twiddle-files
in your program,
and send mail to ‘bug-gnu-emacs@prep.ai.mit.edu’ suggesting we add
it to Emacs. If and when we do, we can change the name easily enough.
If one prefix is insufficient, your package may use two or three alternative common prefixes, so long as they make sense.
Separate the prefix from the rest of the symbol name with a hyphen, ‘-’. This will be consistent with XEmacs itself and with most Emacs Lisp programs.
provide
in each separate
library program, at least if there is more than one entry point to the
program.
require
to make sure they are loaded.
(eval-when-compile (require 'bar)) |
(And bar should contain (provide 'bar)
, to make the
require
work.) This will cause bar to be loaded when you
byte-compile foo. Otherwise, you risk compiling foo without
the necessary macro loaded, and that would produce compiled code that
won’t work right. See section Macros and Byte Compilation.
Using eval-when-compile
avoids loading bar when
the compiled version of foo is used.
run-hooks
, just as the existing major modes do. See section Hooks.
framep
and frame-live-p
.
Instead, define sequences consisting of C-c followed by a non-letter. 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 that work go to waste, and inconvenience users.
The reason for this rule is that a non-prefix binding for <ESC> in any context prevents recognition of escape sequences as function keys in that context.
whatever-mode
which turns the feature on or
off, and make it autoload (see section 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.
next-line
or previous-line
in programs; nearly
always, forward-line
is more convenient as well as more
predictable and robust. See section Motion by Text Lines.
In particular, don’t use these functions:
beginning-of-buffer
, end-of-buffer
replace-string
, replace-regexp
If you just want to move point, or replace a certain string, without any of the other features intended for interactive users, you can replace these functions with one or two lines of simple Lisp code.
Vectors are advantageous for tables that are substantial in size and are accessed in random order (not searched front to back), provided there is no need to insert or delete elements (only lists allow that).
message
function, not princ
. See section The Echo Area.
error
(or signal
). The function error
does not return.
See section How to Signal an Error.
Do not use message
, throw
, sleep-for
,
or beep
to report errors.
edit-options
command does: switch to another buffer and let the
user switch back at will. See section Recursive Editing.
indent-sexp
) using the
default indentation parameters.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are ways of improving the execution speed of byte-compiled Lisp programs.
memq
, member
,
assq
, or assoc
is even faster than explicit iteration. It
may be worth rearranging a data structure so that one of these primitive
search functions can be used.
byte-compile
property. If the property is non-nil
, then the function is
handled specially.
For example, the following input will show you that aref
is
compiled specially (see section Functions that Operate on Arrays) while elt
is not
(see section Sequences):
(get 'aref 'byte-compile) ⇒ byte-compile-two-args (get 'elt 'byte-compile) ⇒ nil |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some tips for the writing of documentation strings.
The documentation string can have additional lines that 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.
However, rather than simply filling the entire documentation string, you can make it much more readable by choosing line breaks with care. Use blank lines between topics if the documentation string is long.
nil
values are equivalent and indicate explicitly what
nil
and non-nil
mean.
/
refers to its second argument as ‘DIVISOR’, because the
actual argument name is divisor
.
Also use all caps for meta-syntactic variables, such as when you show the decomposition of a list or vector into subunits, some of which may vary.
forward-char
. (This is normally ‘C-f’,
but it may be some other character if the user has moved key bindings.)
See section Substituting Key Bindings in Documentation.
It is not practical to use ‘\\[…]’ very many times, because display of the documentation string will become slow. So use this to describe the most important commands in your major mode, and then use ‘\\{…}’ to display the rest of the mode’s keymap.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
We recommend these conventions for where to put comments and how to indent them:
Comments that start with a single semicolon, ‘;’, should all be
aligned to the same column on the right of the source code. Such
comments usually explain how the code on the same line does its job. In
Lisp mode and related modes, the M-; (indent-for-comment
)
command automatically inserts such a ‘;’ in the right place, or
aligns such a comment if it is already present.
This and following examples are taken from the Emacs sources.
(setq base-version-list ; there was a base (assoc (subseq fn 0 start-vn) ; version to which file-version-assoc-list)) ; this looks like ; a subversion |
Comments that start with two semicolons, ‘;;’, should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. For example:
(prog1 (setq auto-fill-function … … ;; update modeline (redraw-modeline))) |
Every function that has no documentation string (because it is used only internally within the package it belongs to), should have instead a two-semicolon comment right before the function, explaining what the function does and how to call it properly. Explain precisely what each argument means and how the function interprets its possible values.
Comments that start with three semicolons, ‘;;;’, should start at the left margin. Such comments are used outside function definitions to make general statements explaining the design principles of the program. For example:
;;; This Lisp code is run in XEmacs ;;; when it is to operate as a server ;;; for other processes. |
Another use for triple-semicolon comments is for commenting out lines within a function. We use triple-semicolons for this precisely so that they remain at the left margin.
(defun foo (a) ;;; This is no longer necessary. ;;; (force-mode-line-update) (message "Finished with %s" a)) |
Comments that start with four semicolons, ‘;;;;’, should be aligned to the left margin and are used for headings of major sections of a program. For example:
;;;; The kill ring |
The indentation commands of the Lisp modes in XEmacs, such as M-;
(indent-for-comment
) and <TAB> (lisp-indent-line
)
automatically indent comments according to these conventions,
depending on the number of semicolons. See (xemacs)Comments section ‘Manipulating Comments’ in The XEmacs User’s Manual.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.