update.
[chise/xemacs-chise.git.1] / man / lispref / tips.texi
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/tips.info
6 @node Tips, Building XEmacs and Object Allocation, MULE, Top
7 @appendix Tips and Standards
8 @cindex tips
9 @cindex standards of coding style
10 @cindex coding standards
11
12   This chapter describes no additional features of XEmacs Lisp.
13 Instead it gives advice on making effective use of the features described
14 in the previous chapters.
15
16 @menu
17 * Style Tips::                Writing clean and robust programs.
18 * Compilation Tips::          Making compiled code run fast.
19 * Documentation Tips::        Writing readable documentation strings.
20 * Comment Tips::              Conventions for writing comments.
21 * Library Headers::           Standard headers for library packages.
22 @end menu
23
24 @node Style Tips
25 @section Writing Clean Lisp Programs
26
27   Here are some tips for avoiding common errors in writing Lisp code
28 intended for widespread use:
29
30 @itemize @bullet
31 @item
32 Since all global variables share the same name space, and all functions
33 share another name space, you should choose a short word to distinguish
34 your program from other Lisp programs.  Then take care to begin the
35 names of all global variables, constants, and functions with the chosen
36 prefix.  This helps avoid name conflicts.
37
38 This recommendation applies even to names for traditional Lisp
39 primitives that are not primitives in XEmacs Lisp---even to @code{cadr}.
40 Believe it or not, there is more than one plausible way to define
41 @code{cadr}.  Play it safe; append your name prefix to produce a name
42 like @code{foo-cadr} or @code{mylib-cadr} instead.
43
44 If you write a function that you think ought to be added to Emacs under
45 a certain name, such as @code{twiddle-files}, don't call it by that name
46 in your program.  Call it @code{mylib-twiddle-files} in your program,
47 and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
48 it to Emacs.  If and when we do, we can change the name easily enough.
49
50 If one prefix is insufficient, your package may use two or three
51 alternative common prefixes, so long as they make sense.
52
53 Separate the prefix from the rest of the symbol name with a hyphen,
54 @samp{-}.  This will be consistent with XEmacs itself and with most Emacs
55 Lisp programs.
56
57 @item
58 It is often useful to put a call to @code{provide} in each separate
59 library program, at least if there is more than one entry point to the
60 program.
61
62 @item
63 If a file requires certain other library programs to be loaded
64 beforehand, then the comments at the beginning of the file should say
65 so.  Also, use @code{require} to make sure they are loaded.
66
67 @item
68 If one file @var{foo} uses a macro defined in another file @var{bar},
69 @var{foo} should contain this expression before the first use of the
70 macro:
71
72 @example
73 (eval-when-compile (require '@var{bar}))
74 @end example
75
76 @noindent
77 (And @var{bar} should contain @code{(provide '@var{bar})}, to make the
78 @code{require} work.)  This will cause @var{bar} to be loaded when you
79 byte-compile @var{foo}.  Otherwise, you risk compiling @var{foo} without
80 the necessary macro loaded, and that would produce compiled code that
81 won't work right.  @xref{Compiling Macros}.
82
83 Using @code{eval-when-compile} avoids loading @var{bar} when
84 the compiled version of @var{foo} is @emph{used}.
85
86 @item
87 If you define a major mode, make sure to run a hook variable using
88 @code{run-hooks}, just as the existing major modes do.  @xref{Hooks}.
89
90 @item
91 If the purpose of a function is to tell you whether a certain condition
92 is true or false, give the function a name that ends in @samp{p}.  If
93 the name is one word, add just @samp{p}; if the name is multiple words,
94 add @samp{-p}.  Examples are @code{framep} and @code{frame-live-p}.
95
96 @item
97 If a user option variable records a true-or-false condition, give it a
98 name that ends in @samp{-flag}.
99
100 @item
101 Please do not define @kbd{C-c @var{letter}} as a key in your major
102 modes.  These sequences are reserved for users; they are the
103 @strong{only} sequences reserved for users, so we cannot do without
104 them.
105
106 Instead, define sequences consisting of @kbd{C-c} followed by a
107 non-letter.  These sequences are reserved for major modes.
108
109 Changing all the major modes in Emacs 18 so they would follow this
110 convention was a lot of work.  Abandoning this convention would make
111 that work go to waste, and inconvenience users.
112
113 @item
114 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
115 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
116
117 @item
118 Sequences consisting of @kbd{C-c} followed by any other punctuation
119 character are allocated for minor modes.  Using them in a major mode is
120 not absolutely prohibited, but if you do that, the major mode binding
121 may be shadowed from time to time by minor modes.
122
123 @item
124 You should not bind @kbd{C-h} following any prefix character (including
125 @kbd{C-c}).  If you don't bind @kbd{C-h}, it is automatically available
126 as a help character for listing the subcommands of the prefix character.
127
128 @item
129 You should not bind a key sequence ending in @key{ESC} except following
130 another @key{ESC}.  (That is, it is ok to bind a sequence ending in
131 @kbd{@key{ESC} @key{ESC}}.)
132
133 The reason for this rule is that a non-prefix binding for @key{ESC} in
134 any context prevents recognition of escape sequences as function keys in
135 that context.
136
137 @item
138 Applications should not bind mouse events based on button 1 with the
139 shift key held down.  These events include @kbd{S-mouse-1},
140 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on.  They are reserved for
141 users.
142
143 @item
144 Modes should redefine @kbd{mouse-2} as a command to follow some sort of
145 reference in the text of a buffer, if users usually would not want to
146 alter the text in that buffer by hand.  Modes such as Dired, Info,
147 Compilation, and Occur redefine it in this way.
148
149 @item
150 When a package provides a modification of ordinary Emacs behavior, it is
151 good to include a command to enable and disable the feature, Provide a
152 command named @code{@var{whatever}-mode} which turns the feature on or
153 off, and make it autoload (@pxref{Autoload}).  Design the package so
154 that simply loading it has no visible effect---that should not enable
155 the feature.  Users will request the feature by invoking the command.
156
157 @item
158 It is a bad idea to define aliases for the Emacs primitives.  Use the
159 standard names instead.
160
161 @item
162 Redefining an Emacs primitive is an even worse idea.
163 It may do the right thing for a particular program, but
164 there is no telling what other programs might break as a result.
165
166 @item
167 If a file does replace any of the functions or library programs of
168 standard XEmacs, prominent comments at the beginning of the file should
169 say which functions are replaced, and how the behavior of the
170 replacements differs from that of the originals.
171
172 @item
173 Please keep the names of your XEmacs Lisp source files to 13 characters
174 or less.  This way, if the files are compiled, the compiled files' names
175 will be 14 characters or less, which is short enough to fit on all kinds
176 of Unix systems.
177
178 @item
179 Don't use @code{next-line} or @code{previous-line} in programs; nearly
180 always, @code{forward-line} is more convenient as well as more
181 predictable and robust.  @xref{Text Lines}.
182
183 @item
184 Don't call functions that set the mark, unless setting the mark is one
185 of the intended features of your program.  The mark is a user-level
186 feature, so it is incorrect to change the mark except to supply a value
187 for the user's benefit.  @xref{The Mark}.
188
189 In particular, don't use these functions:
190
191 @itemize @bullet
192 @item
193 @code{beginning-of-buffer}, @code{end-of-buffer}
194 @item
195 @code{replace-string}, @code{replace-regexp}
196 @end itemize
197
198 If you just want to move point, or replace a certain string, without any
199 of the other features intended for interactive users, you can replace
200 these functions with one or two lines of simple Lisp code.
201
202 @item
203 Use lists rather than vectors, except when there is a particular reason
204 to use a vector.  Lisp has more facilities for manipulating lists than
205 for vectors, and working with lists is usually more convenient.
206
207 Vectors are advantageous for tables that are substantial in size and are
208 accessed in random order (not searched front to back), provided there is
209 no need to insert or delete elements (only lists allow that).
210
211 @item
212 The recommended way to print a message in the echo area is with
213 the @code{message} function, not @code{princ}.  @xref{The Echo Area}.
214
215 @item
216 When you encounter an error condition, call the function @code{error}
217 (or @code{signal}).  The function @code{error} does not return.
218 @xref{Signaling Errors}.
219
220 Do not use @code{message}, @code{throw}, @code{sleep-for},
221 or @code{beep} to report errors.
222
223 @item
224 An error message should start with a capital letter but should not end
225 with a period.
226
227 @item
228 Try to avoid using recursive edits.  Instead, do what the Rmail @kbd{e}
229 command does: use a new local keymap that contains one command defined
230 to switch back to the old local keymap.  Or do what the
231 @code{edit-options} command does: switch to another buffer and let the
232 user switch back at will.  @xref{Recursive Editing}.
233
234 @item
235 In some other systems there is a convention of choosing variable names
236 that begin and end with @samp{*}.  We don't use that convention in Emacs
237 Lisp, so please don't use it in your programs.  (Emacs uses such names
238 only for program-generated buffers.)  The users will find Emacs more
239 coherent if all libraries use the same conventions.
240
241 @item
242 Use names starting with a space for temporary buffers (@pxref{Buffer
243 Names}), or at least call @code{buffer-disable-undo} on them.  Otherwise
244 they may stay referenced by internal undo variable(s) after getting
245 killed.  If this happens before dumping (@pxref{Building XEmacs}), this
246 may cause fatal error when portable dumper is used.
247
248 @item
249 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
250 default indentation parameters.
251
252 @item
253 Don't make a habit of putting close-parentheses on lines by themselves;
254 Lisp programmers find this disconcerting.  Once in a while, when there
255 is a sequence of many consecutive close-parentheses, it may make sense
256 to split them in one or two significant places.
257
258 @item
259 Please put a copyright notice on the file if you give copies to anyone.
260 Use the same lines that appear at the top of the Lisp files in XEmacs
261 itself.  If you have not signed papers to assign the copyright to the
262 Foundation, then place your name in the copyright notice in place of the
263 Foundation's name.
264 @end itemize
265
266 @node Compilation Tips
267 @section Tips for Making Compiled Code Fast
268 @cindex execution speed
269 @cindex speedups
270
271   Here are ways of improving the execution speed of byte-compiled
272 Lisp programs.
273
274 @itemize @bullet
275 @item
276 @cindex profiling
277 @cindex timing programs
278 @cindex @file{profile.el}
279 Use the @file{profile} library to profile your program.  See the file
280 @file{profile.el} for instructions.
281
282 @item
283 Use iteration rather than recursion whenever possible.
284 Function calls are slow in XEmacs Lisp even when a compiled function
285 is calling another compiled function.
286
287 @item
288 Using the primitive list-searching functions @code{memq}, @code{member},
289 @code{assq}, or @code{assoc} is even faster than explicit iteration.  It
290 may be worth rearranging a data structure so that one of these primitive
291 search functions can be used.
292
293 @item
294 Certain built-in functions are handled specially in byte-compiled code,
295 avoiding the need for an ordinary function call.  It is a good idea to
296 use these functions rather than alternatives.  To see whether a function
297 is handled specially by the compiler, examine its @code{byte-compile}
298 property.  If the property is non-@code{nil}, then the function is
299 handled specially.
300
301 For example, the following input will show you that @code{aref} is
302 compiled specially (@pxref{Array Functions}) while @code{elt} is not
303 (@pxref{Sequence Functions}):
304
305 @example
306 @group
307 (get 'aref 'byte-compile)
308      @result{} byte-compile-two-args
309 @end group
310
311 @group
312 (get 'elt 'byte-compile)
313      @result{} nil
314 @end group
315 @end example
316
317 @item
318 If calling a small function accounts for a  substantial part of your
319 program's running time, make the function inline.  This eliminates
320 the function call overhead.  Since making a function inline reduces
321 the flexibility of changing the program, don't do it unless it gives
322 a noticeable speedup in something slow enough that users care about
323 the speed.  @xref{Inline Functions}.
324 @end itemize
325
326 @node Documentation Tips
327 @section Tips for Documentation Strings
328
329   Here are some tips for the writing of documentation strings.
330
331 @itemize @bullet
332 @item
333 Every command, function, or variable intended for users to know about
334 should have a documentation string.
335
336 @item
337 An internal variable or subroutine of a Lisp program might as well have
338 a documentation string.  In earlier Emacs versions, you could save space
339 by using a comment instead of a documentation string, but that is no
340 longer the case.
341
342 @item
343 The first line of the documentation string should consist of one or two
344 complete sentences that stand on their own as a summary.  @kbd{M-x
345 apropos} displays just the first line, and if it doesn't stand on its
346 own, the result looks bad.  In particular, start the first line with a
347 capital letter and end with a period.
348
349 The documentation string can have additional lines that expand on the
350 details of how to use the function or variable.  The additional lines
351 should be made up of complete sentences also, but they may be filled if
352 that looks good.
353
354 @item
355 For consistency, phrase the verb in the first sentence of a
356 documentation string as an infinitive with ``to'' omitted.  For
357 instance, use ``Return the cons of A and B.'' in preference to ``Returns
358 the cons of A and B@.''  Usually it looks good to do likewise for the
359 rest of the first paragraph.  Subsequent paragraphs usually look better
360 if they have proper subjects.
361
362 @item
363 Write documentation strings in the active voice, not the passive, and in
364 the present tense, not the future.  For instance, use ``Return a list
365 containing A and B.'' instead of ``A list containing A and B will be
366 returned.''
367
368 @item
369 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
370 Instead of, ``Cause Emacs to display text in boldface,'' write just
371 ``Display text in boldface.''
372
373 @item
374 Do not start or end a documentation string with whitespace.
375
376 @item
377 Format the documentation string so that it fits in an Emacs window on an
378 80-column screen.  It is a good idea for most lines to be no wider than
379 60 characters.  The first line can be wider if necessary to fit the
380 information that ought to be there.
381
382 However, rather than simply filling the entire documentation string, you
383 can make it much more readable by choosing line breaks with care.
384 Use blank lines between topics if the documentation string is long.
385
386 @item
387 @strong{Do not} indent subsequent lines of a documentation string so
388 that the text is lined up in the source code with the text of the first
389 line.  This looks nice in the source code, but looks bizarre when users
390 view the documentation.  Remember that the indentation before the
391 starting double-quote is not part of the string!
392
393 @item
394 A variable's documentation string should start with @samp{*} if the
395 variable is one that users would often want to set interactively.  If
396 the value is a long list, or a function, or if the variable would be set
397 only in init files, then don't start the documentation string with
398 @samp{*}.  @xref{Defining Variables}.
399
400 @item
401 The documentation string for a variable that is a yes-or-no flag should
402 start with words such as ``Non-nil means@dots{}'', to make it clear that
403 all non-@code{nil} values are equivalent and indicate explicitly what
404 @code{nil} and non-@code{nil} mean.
405
406 @item
407 When a function's documentation string mentions the value of an argument
408 of the function, use the argument name in capital letters as if it were
409 a name for that value.  Thus, the documentation string of the function
410 @code{/} refers to its second argument as @samp{DIVISOR}, because the
411 actual argument name is @code{divisor}.
412
413 Also use all caps for meta-syntactic variables, such as when you show
414 the decomposition of a list or vector into subunits, some of which may
415 vary.
416
417 @item
418 @iftex
419 When a documentation string refers to a Lisp symbol, write it as it
420 would be printed (which usually means in lower case), with single-quotes
421 around it.  For example: @samp{`lambda'}.  There are two exceptions:
422 write @code{t} and @code{nil} without single-quotes.
423 @end iftex
424 @ifinfo
425 When a documentation string refers to a Lisp symbol, write it as it
426 would be printed (which usually means in lower case), with single-quotes
427 around it.  For example: @samp{lambda}.  There are two exceptions: write
428 t and nil without single-quotes.  (In this manual, we normally do use
429 single-quotes for those symbols.)
430 @end ifinfo
431
432 @item
433 Don't write key sequences directly in documentation strings.  Instead,
434 use the @samp{\\[@dots{}]} construct to stand for them.  For example,
435 instead of writing @samp{C-f}, write @samp{\\[forward-char]}.  When
436 Emacs displays the documentation string, it substitutes whatever key is
437 currently bound to @code{forward-char}.  (This is normally @samp{C-f},
438 but it may be some other character if the user has moved key bindings.)
439 @xref{Keys in Documentation}.
440
441 @item
442 In documentation strings for a major mode, you will want to refer to the
443 key bindings of that mode's local map, rather than global ones.
444 Therefore, use the construct @samp{\\<@dots{}>} once in the
445 documentation string to specify which key map to use.  Do this before
446 the first use of @samp{\\[@dots{}]}.  The text inside the
447 @samp{\\<@dots{}>} should be the name of the variable containing the
448 local keymap for the major mode.
449
450 It is not practical to use @samp{\\[@dots{}]} very many times, because
451 display of the documentation string will become slow.  So use this to
452 describe the most important commands in your major mode, and then use
453 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
454 @end itemize
455
456 @node Comment Tips
457 @section Tips on Writing Comments
458
459   We recommend these conventions for where to put comments and how to
460 indent them:
461
462 @table @samp
463 @item ;
464 Comments that start with a single semicolon, @samp{;}, should all be
465 aligned to the same column on the right of the source code.  Such
466 comments usually explain how the code on the same line does its job.  In
467 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
468 command automatically inserts such a @samp{;} in the right place, or
469 aligns such a comment if it is already present.
470
471 This and following examples are taken from the Emacs sources.
472
473 @smallexample
474 @group
475 (setq base-version-list                 ; there was a base
476       (assoc (substring fn 0 start-vn)  ; version to which
477              file-version-assoc-list))  ; this looks like
478                                         ; a subversion
479 @end group
480 @end smallexample
481
482 @item ;;
483 Comments that start with two semicolons, @samp{;;}, should be aligned to
484 the same level of indentation as the code.  Such comments usually
485 describe the purpose of the following lines or the state of the program
486 at that point.  For example:
487
488 @smallexample
489 @group
490 (prog1 (setq auto-fill-function
491              @dots{}
492              @dots{}
493   ;; update modeline
494   (redraw-modeline)))
495 @end group
496 @end smallexample
497
498 Every function that has no documentation string (because it is used only
499 internally within the package it belongs to), should have instead a
500 two-semicolon comment right before the function, explaining what the
501 function does and how to call it properly.  Explain precisely what each
502 argument means and how the function interprets its possible values.
503
504 @item ;;;
505 Comments that start with three semicolons, @samp{;;;}, should start at
506 the left margin.  Such comments are used outside function definitions to
507 make general statements explaining the design principles of the program.
508 For example:
509
510 @smallexample
511 @group
512 ;;; This Lisp code is run in XEmacs
513 ;;; when it is to operate as a server
514 ;;; for other processes.
515 @end group
516 @end smallexample
517
518 Another use for triple-semicolon comments is for commenting out lines
519 within a function.  We use triple-semicolons for this precisely so that
520 they remain at the left margin.
521
522 @smallexample
523 (defun foo (a)
524 ;;; This is no longer necessary.
525 ;;;  (force-mode-line-update)
526   (message "Finished with %s" a))
527 @end smallexample
528
529 @item ;;;;
530 Comments that start with four semicolons, @samp{;;;;}, should be aligned
531 to the left margin and are used for headings of major sections of a
532 program.  For example:
533
534 @smallexample
535 ;;;; The kill ring
536 @end smallexample
537 @end table
538
539 @noindent
540 The indentation commands of the Lisp modes in XEmacs, such as @kbd{M-;}
541 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
542 automatically indent comments according to these conventions,
543 depending on the number of semicolons.  @xref{Comments,,
544 Manipulating Comments, xemacs, The XEmacs User's Manual}.
545
546 @node Library Headers
547 @section Conventional Headers for XEmacs Libraries
548 @cindex header comments
549 @cindex library header comments
550
551   XEmacs has conventions for using special comments in Lisp libraries
552 to divide them into sections and give information such as who wrote
553 them.  This section explains these conventions.  First, an example:
554
555 @smallexample
556 @group
557 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
558
559 ;; Copyright (C) 1992 Free Software Foundation, Inc.
560 @end group
561
562 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
563 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
564 ;; Created: 14 Jul 1992
565 ;; Version: 1.2
566 @group
567 ;; Keywords: docs
568
569 ;; This file is part of XEmacs.
570 @var{copying permissions}@dots{}
571 @end group
572 @end smallexample
573
574   The very first line should have this format:
575
576 @example
577 ;;; @var{filename} --- @var{description}
578 @end example
579
580 @noindent
581 The description should be complete in one line.
582
583   After the copyright notice come several @dfn{header comment} lines,
584 each beginning with @samp{;; @var{header-name}:}.  Here is a table of
585 the conventional possibilities for @var{header-name}:
586
587 @table @samp
588 @item Author
589 This line states the name and net address of at least the principal
590 author of the library.
591
592 If there are multiple authors, you can list them on continuation lines
593 led by @code{;;} and a tab character, like this:
594
595 @smallexample
596 @group
597 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
598 ;;      Dave Sill <de5@@ornl.gov>
599 ;;      Dave Brennan <brennan@@hal.com>
600 ;;      Eric Raymond <esr@@snark.thyrsus.com>
601 @end group
602 @end smallexample
603
604 @item Maintainer
605 This line should contain a single name/address as in the Author line, or
606 an address only, or the string @samp{FSF}.  If there is no maintainer
607 line, the person(s) in the Author field are presumed to be the
608 maintainers.  The example above is mildly bogus because the maintainer
609 line is redundant.
610
611 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
612 possible a Lisp function to ``send mail to the maintainer'' without
613 having to mine the name out by hand.
614
615 Be sure to surround the network address with @samp{<@dots{}>} if
616 you include the person's full name as well as the network address.
617
618 @item Created
619 This optional line gives the original creation date of the
620 file.  For historical interest only.
621
622 @item Version
623 If you wish to record version numbers for the individual Lisp program, put
624 them in this line.
625
626 @item Adapted-By
627 In this header line, place the name of the person who adapted the
628 library for installation (to make it fit the style conventions, for
629 example).
630
631 @item Keywords
632 This line lists keywords for the @code{finder-by-keyword} help command.
633 This field is important; it's how people will find your package when
634 they're looking for things by topic area.  To separate the keywords, you
635 can use spaces, commas, or both.
636 @end table
637
638   Just about every Lisp library ought to have the @samp{Author} and
639 @samp{Keywords} header comment lines.  Use the others if they are
640 appropriate.  You can also put in header lines with other header
641 names---they have no standard meanings, so they can't do any harm.
642
643   We use additional stylized comments to subdivide the contents of the
644 library file.  Here is a table of them:
645
646 @table @samp
647 @item ;;; Commentary:
648 This begins introductory comments that explain how the library works.
649 It should come right after the copying permissions.
650
651 @item ;;; Change log:
652 This begins change log information stored in the library file (if you
653 store the change history there).  For most of the Lisp
654 files distributed with XEmacs, the change history is kept in the file
655 @file{ChangeLog} and not in the source file at all; these files do
656 not have a @samp{;;; Change log:} line.
657
658 @item ;;; Code:
659 This begins the actual code of the program.
660
661 @item ;;; @var{filename} ends here
662 This is the @dfn{footer line}; it appears at the very end of the file.
663 Its purpose is to enable people to detect truncated versions of the file
664 from the lack of a footer line.
665 @end table