comparison lispref/tips.texi @ 6552:3b84ed22f747

Initial revision
author Richard M. Stallman <rms@gnu.org>
date Mon, 28 Mar 1994 05:41:05 +0000
parents
children 3b19456b877a
comparison
equal deleted inserted replaced
6551:99ca8123a3ca 6552:3b84ed22f747
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/tips
6 @node Tips, GNU Emacs Internals, Calendar, 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 Emacs 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 Emacs 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 Emacs 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 one file @var{foo} uses a macro defined in another file @var{bar},
64 @var{foo} should contain @code{(require '@var{bar})} before the first
65 use of the macro. (And @var{bar} should contain @code{(provide
66 '@var{bar})}, to make the @code{require} work.) This will cause
67 @var{bar} to be loaded when you byte-compile @var{foo}. Otherwise, you
68 risk compiling @var{foo} without the necessary macro loaded, and that
69 would produce compiled code that won't work right. @xref{Compiling
70 Macros}.
71
72 @item
73 If you define a major mode, make sure to run a hook variable using
74 @code{run-hooks}, just as the existing major modes do. @xref{Hooks}.
75
76 @item
77 Please do not define @kbd{C-c @var{letter}} as a key in your major
78 modes. These sequences are reserved for users; they are the
79 @strong{only} sequences reserved for users, so we cannot do without
80 them.
81
82 Instead, define sequences consisting of @kbd{C-c} followed by a
83 non-letter. These sequences are reserved for major modes.
84
85 Changing all the major modes in Emacs 18 so they would follow this
86 convention was a lot of work. Abandoning this convention would waste
87 that work and inconvenience the users.
88
89 @item
90 You should not bind @kbd{C-h} following any prefix character (including
91 @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
92 as a help character for listing the subcommands of the prefix character.
93
94 @item
95 You should not bind a key sequence ending in @key{ESC} except following
96 another @key{ESC}. (That is, it is ok to bind a sequence ending in
97 @kbd{@key{ESC} @key{ESC}}.)
98
99 The reason for this rule is that a non-prefix binding for @key{ESC} in
100 any context prevents recognition of escape sequences as function keys in
101 that context.
102
103 @item
104 It is a bad idea to define aliases for the Emacs primitives.
105 Use the standard names instead.
106
107 @item
108 Redefining an Emacs primitive is an even worse idea.
109 It may do the right thing for a particular program, but
110 there is no telling what other programs might break as a result.
111
112 @item
113 If a file does replace any of the functions or library programs of
114 standard Emacs, prominent comments at the beginning of the file should
115 say which functions are replaced, and how the behavior of the
116 replacements differs from that of the originals.
117
118 @item
119 If a file requires certain standard library programs to be loaded
120 beforehand, then the comments at the beginning of the file should say
121 so.
122
123 @item
124 Please keep the names of your Emacs Lisp source files to 13 characters
125 or less. This way, if the files are compiled, the compiled files' names
126 will be 14 characters or less, which is short enough to fit on all kinds
127 of Unix systems.
128
129 @item
130 Don't use @code{next-line} or @code{previous-line} in programs; nearly
131 always, @code{forward-line} is more convenient as well as more
132 predictable and robust. @xref{Text Lines}.
133
134 @item
135 Don't use functions that set the mark in your Lisp code (unless you are
136 writing a command to set the mark). The mark is a user-level feature,
137 so it is incorrect to change the mark except to supply a value for the
138 user's benefit. @xref{The Mark}.
139
140 In particular, don't use these functions:
141
142 @itemize @bullet
143 @item
144 @code{beginning-of-buffer}, @code{end-of-buffer}
145 @item
146 @code{replace-string}, @code{replace-regexp}
147 @end itemize
148
149 If you just want to move point, or replace a certain string, without any
150 of the other features intended for interactive users, you can replace
151 these functions with one or two lines of simple Lisp code.
152
153 @item
154 The recommended way to print a message in the echo area is with
155 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
156
157 @item
158 When you encounter an error condition, call the function @code{error}
159 (or @code{signal}). The function @code{error} does not return.
160 @xref{Signaling Errors}.
161
162 Do not use @code{message}, @code{throw}, @code{sleep-for},
163 or @code{beep} to report errors.
164
165 @item
166 Avoid using recursive edits. Instead, do what the Rmail @kbd{w} command
167 does: use a new local keymap that contains one command defined to
168 switch back to the old local keymap. Or do what the @code{edit-options}
169 command does: switch to another buffer and let the user switch back at
170 will. @xref{Recursive Editing}.
171
172 @item
173 In some other systems there is a convention of choosing variable names
174 that begin and end with @samp{*}. We don't use that convention in Emacs
175 Lisp, so please don't use it in your library. (In fact, in Emacs names
176 of this form are conventionally used for program-generated buffers.) The
177 users will find Emacs more coherent if all libraries use the same
178 conventions.
179
180 @item
181 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
182 default indentation parameters.
183
184 @item
185 Don't make a habit of putting close-parentheses on lines by themselves;
186 Lisp programmers find this disconcerting. Once in a while, when there
187 is a sequence of many consecutive close-parentheses, it may make sense
188 to split them in one or two significant places.
189
190 @item
191 Please put a copyright notice on the file if you give copies to anyone.
192 Use the same lines that appear at the top of the Lisp files in Emacs
193 itself. If you have not signed papers to assign the copyright to the
194 Foundation, then place your name in the copyright notice in place of the
195 Foundation's name.
196 @end itemize
197
198 @node Compilation Tips
199 @section Tips for Making Compiled Code Fast
200 @cindex execution speed
201 @cindex speedups
202
203 Here are ways of improving the execution speed of byte-compiled
204 lisp programs.
205
206 @itemize @bullet
207 @item
208 @cindex profiling
209 @cindex timing programs
210 @cindex @file{profile.el}
211 Use the @file{profile} library to profile your program. See the file
212 @file{profile.el} for instructions.
213
214 @item
215 Use iteration rather than recursion whenever possible.
216 Function calls are slow in Emacs Lisp even when a compiled function
217 is calling another compiled function.
218
219 @item
220 Using the primitive list-searching functions @code{memq}, @code{assq} or
221 @code{assoc} is even faster than explicit iteration. It may be worth
222 rearranging a data structure so that one of these primitive search
223 functions can be used.
224
225 @item
226 Certain built-in functions are handled specially by the byte compiler
227 avoiding the need for an ordinary function call. It is a good idea to
228 use these functions rather than alternatives. To see whether a function
229 is handled specially by the compiler, examine its @code{byte-compile}
230 property. If the property is non-@code{nil}, then the function is
231 handled specially.
232
233 For example, the following input will show you that @code{aref} is
234 compiled specially (@pxref{Array Functions}) while @code{elt} is not
235 (@pxref{Sequence Functions}):
236
237 @smallexample
238 @group
239 (get 'aref 'byte-compile)
240 @result{} byte-compile-two-args
241 @end group
242
243 @group
244 (get 'elt 'byte-compile)
245 @result{} nil
246 @end group
247 @end smallexample
248
249 @item
250 If calling a small function accounts for a substantial part of your
251 program's running time, make the function inline. This eliminates
252 the function call overhead. Since making a function inline reduces
253 the flexibility of changing the program, don't do it unless it gives
254 a noticeable speedup in something slow enough for users to care about
255 the speed. @xref{Inline Functions}.
256 @end itemize
257
258 @node Documentation Tips
259 @section Tips for Documentation Strings
260
261 Here are some tips for the writing of documentation strings.
262
263 @itemize @bullet
264 @item
265 Every command, function or variable intended for users to know about
266 should have a documentation string.
267
268 @item
269 An internal subroutine of a Lisp program need not have a documentation
270 string, and you can save space by using a comment instead.
271
272 @item
273 The first line of the documentation string should consist of one or two
274 complete sentences which stand on their own as a summary. In particular,
275 start the line with a capital letter and end with a period.
276 For instance, use ``Return the cons of A and B.'' in preference to
277 ``Returns the cons of A and B@.''
278
279 The documentation string can have additional lines which expand on the
280 details of how to use the function or variable. The additional lines
281 should be made up of complete sentences also, but they may be filled if
282 that looks good.
283
284 @item
285 Write documentation strings in the active voice, not the passive, and in
286 the present tense, not the future. For instance, use ``Return a list
287 containing A and B.'' instead of ``A list containing A and B will be
288 returned.''
289
290 @item
291 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
292 Instead of, ``Cause Emacs to display text in boldface,'' write just
293 ``Display text in boldface.''
294
295 @item
296 Do not start or end a documentation string with whitespace.
297
298 @item
299 Format the documentation string so that it fits in an Emacs window on an
300 80 column screen. It is a good idea for most lines to be no wider than
301 60 characters. The first line can be wider if necessary to fit the
302 information that ought to be there.
303
304 However, rather than simply filling the entire documentation string, you
305 can make it much more readable by choosing line breaks with care.
306 Use blank lines between topics if the documentation string is long.
307
308 @item
309 @strong{Do not} indent subsequent lines of a documentation string so
310 that the text is lined up in the source code with the text of the first
311 line. This looks nice in the source code, but looks bizarre when users
312 view the documentation. Remember that the indentation before the
313 starting double-quote is not part of the string!
314
315 @item
316 A variable's documentation string should start with @samp{*} if the
317 variable is one that users would want to set interactively often. If
318 the value is a long list, or a function, or if the variable would only
319 be set in init files, then don't start the documentation string with
320 @samp{*}. @xref{Defining Variables}.
321
322 @item
323 The documentation string for a variable that is a yes-or-no flag should
324 start with words such as ``Non-nil means@dots{}'', to make it clear both
325 that the variable only has two meaningfully distinct values and which value
326 means ``yes''.
327
328 @item
329 When a function's documentation string mentions the value of an argument
330 of the function, use the argument name in capital letters as if it were
331 a name for that value. Thus, the documentation string of the function
332 @code{/} refers to its second argument as @samp{DIVISOR}.
333
334 Also use all caps for meta-syntactic variables, such as when you show
335 the decomposition of a list or vector into subunits, some of which may
336 vary.
337
338 @item
339 @iftex
340 When a documentation string refers to a Lisp symbol, write it as it
341 would be printed (which usually means in lower case), with single-quotes
342 around it. For example: @samp{`lambda'}. There are two exceptions:
343 write @code{t} and @code{nil} without single-quotes.
344 @end iftex
345 @ifinfo
346 When a documentation string refers to a Lisp symbol, write it as it
347 would be printed (which usually means in lower case), with single-quotes
348 around it. For example: @samp{lambda}. There are two exceptions: write
349 t and nil without single-quotes. (In this manual, we normally do use
350 single-quotes for those symbols.)
351 @end ifinfo
352
353 @item
354 Don't write key sequences directly in documentation strings. Instead,
355 use the @samp{\\[@dots{}]} construct to stand for them. For example,
356 instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When the
357 documentation string is printed, Emacs will substitute whatever key is
358 currently bound to @code{forward-char}. This will usually be
359 @samp{C-f}, but if the user has moved key bindings, it will be the
360 correct key for that user. @xref{Keys in Documentation}.
361
362 @item
363 In documentation strings for a major mode, you will want to refer to the
364 key bindings of that mode's local map, rather than global ones.
365 Therefore, use the construct @samp{\\<@dots{}>} once in the
366 documentation string to specify which key map to use. Do this before
367 the first use of @samp{\\[@dots{}]}. The text inside the
368 @samp{\\<@dots{}>} should be the name of the variable containing the
369 local keymap for the major mode.
370
371 It is not practical to use @samp{\\[@dots{}]} very many times, because
372 display of the documentation string will become slow. So use this to
373 describe the most important commands in your major mode, and then use
374 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
375
376 @item
377 Don't use the term ``Elisp'', since that is or was a trademark.
378 Use the term ``Emacs Lisp''.
379 @end itemize
380
381 @node Comment Tips
382 @section Tips on Writing Comments
383
384 We recommend these conventions for where to put comments and how to
385 indent them:
386
387 @table @samp
388 @item ;
389 Comments that start with a single semicolon, @samp{;}, should all be
390 aligned to the same column on the right of the source code. Such
391 comments usually explain how the code on the same line does its job. In
392 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
393 command automatically inserts such a @samp{;} in the right place, or
394 aligns such a comment if it is already inserted.
395
396 (The following examples are taken from the Emacs sources.)
397
398 @smallexample
399 @group
400 (setq base-version-list ; there was a base
401 (assoc (substring fn 0 start-vn) ; version to which
402 file-version-assoc-list)) ; this looks like
403 ; a subversion
404 @end group
405 @end smallexample
406
407 @item ;;
408 Comments that start with two semicolons, @samp{;;}, should be aligned to
409 the same level of indentation as the code. Such comments are used to
410 describe the purpose of the following lines or the state of the program
411 at that point. For example:
412
413 @smallexample
414 @group
415 (prog1 (setq auto-fill-function
416 @dots{}
417 @dots{}
418 ;; update mode-line
419 (force-mode-line-update)))
420 @end group
421 @end smallexample
422
423 These comments are also written before a function definition to explain
424 what the function does and how to call it properly.
425
426 @item ;;;
427 Comments that start with three semicolons, @samp{;;;}, should start at
428 the left margin. Such comments are not used within function
429 definitions, but are used to make more general comments. For example:
430
431 @smallexample
432 @group
433 ;;; This Lisp code is run in Emacs
434 ;;; when it is to operate as a server
435 ;;; for other processes.
436 @end group
437 @end smallexample
438
439 @item ;;;;
440 Comments that start with four semicolons, @samp{;;;;}, should be aligned
441 to the left margin and are used for headings of major sections of a
442 program. For example:
443
444 @smallexample
445 ;;;; The kill ring
446 @end smallexample
447 @end table
448
449 @noindent
450 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
451 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
452 automatically indent comments according to these conventions,
453 depending on the the number of semicolons. @xref{Comments,,
454 Manipulating Comments, emacs, The GNU Emacs Manual}.
455
456 If you wish to ``comment out'' a number of lines of code, use triple
457 semicolons at the beginnings of the lines.
458
459 Any character may be included in a comment, but it is advisable to
460 precede a character with syntactic significance in Lisp (such as
461 @samp{\} or unpaired @samp{(} or @samp{)}) with a @samp{\}, to prevent
462 it from confusing the Emacs commands for editing Lisp.
463
464 @node Library Headers
465 @section Conventional Headers for Emacs Libraries
466 @cindex header comments
467 @cindex library header comments
468
469 Emacs 19 has conventions for using special comments in Lisp libraries
470 to divide them into sections and give information such as who wrote
471 them. This section explains these conventions. First, an example:
472
473 @smallexample
474 @group
475 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
476
477 ;; Copyright (C) 1992 Free Software Foundation, Inc.
478 @end group
479
480 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
481 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
482 ;; Created: 14 Jul 1992
483 ;; Version: 1.2
484 @group
485 ;; Keywords: docs
486
487 ;; This file is part of GNU Emacs.
488 @var{copying conditions}@dots{}
489 @end group
490 @end smallexample
491
492 The very first line should have this format:
493
494 @example
495 ;;; @var{filename} --- @var{description}
496 @end example
497
498 @noindent
499 The description should be complete in one line.
500
501 After the copyright notice come several @dfn{header comment} lines,
502 each beginning with @samp{;;; @var{header-name}:}. Here is a table of
503 the conventional possibilities for @var{header-name}:
504
505 @table @samp
506 @item Author
507 This line states the name and net address of at least the principal
508 author of the library.
509
510 If there are multiple authors, you can list them on continuation lines
511 led by @code{;;<TAB>}, like this:
512
513 @smallexample
514 @group
515 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
516 ;; Dave Sill <de5@@ornl.gov>
517 ;; Dave Brennan <brennan@@hal.com>
518 ;; Eric Raymond <esr@@snark.thyrsus.com>
519 @end group
520 @end smallexample
521
522 @item Maintainer
523 This line should contain a single name/address as in the Author line, or
524 an address only, or the string ``FSF''. If there is no maintainer line,
525 the person(s) in the Author field are presumed to be the maintainers.
526 The example above is mildly bogus because the maintainer line is
527 redundant.
528
529 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
530 possible a Lisp function to ``send mail to the maintainer'' without
531 having to mine the name out by hand.
532
533 Be sure to surround the network address with @samp{<@dots{}>} if
534 you include the person's full name as well as the network address.
535
536 @item Created
537 This optional line gives the original creation date of the
538 file. For historical interest only.
539
540 @item Version
541 If you wish to record version numbers for the individual Lisp program, put
542 them in this line.
543
544 @item Adapted-By
545 In this header line, place the name of the person who adapted the
546 library for installation (to make it fit the style conventions, for
547 example).
548
549 @item Keywords
550 This line lists keywords for the @code{finder-by-keyword} help command.
551 This field is important; it's how people will find your package when
552 they're looking for things by topic area.
553 @end table
554
555 Just about every Lisp library ought to have the @samp{Author} and
556 @samp{Keywords} header comment lines. Use the others if they are
557 appropriate. You can also put in header lines with other header
558 names---they have no standard meanings, so they can't do any harm.
559
560 We use additional stylized comments to subdivide the contents of the
561 library file. Here is a table of them:
562
563 @table @samp
564 @item ;;; Commentary:
565 This begins introductory comments that explain how the library works.
566 It should come right after the copying permissions.
567
568 @item ;;; Change log:
569 This begins change log information stored in the library file (if you
570 store the change history there). For most of the Lisp
571 files distributed with Emacs, the change history is kept in the file
572 @file{ChangeLog} and not in the source file at all; these files do
573 not have a @samp{;;; Change log:} line.
574
575 @item ;;; Code:
576 This begins the actual code of the program.
577
578 @item ;;; @var{filename} ends here
579 This is the @dfn{footer line}; it appears at the very end of the file.
580 Its purpose is to enable people to detect truncated versions of the file
581 from the lack of a footer line.
582 @end table