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
9 @cindex standards of coding style
10 @cindex coding standards
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.
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.
25 @section Writing Clean Lisp Programs
27 Here are some tips for avoiding common errors in writing Lisp code
28 intended for widespread use:
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.
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.
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.
50 If one prefix is insufficient, your package may use two or three
51 alternative common prefixes, so long as they make sense.
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
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
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
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}.
77 If the purpose of a function is to tell you whether a certain condition
78 is true or false, give the function a name that ends in @samp{p}. If
79 the name is one word, add just @samp{p}; if the name is multiple words,
80 add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
83 If a user option variable records a true-or-false condition, give it a
84 name that ends in @samp{-flag}.
87 Please do not define @kbd{C-c @var{letter}} as a key in your major
88 modes. These sequences are reserved for users; they are the
89 @strong{only} sequences reserved for users, so we cannot do without
92 Instead, define sequences consisting of @kbd{C-c} followed by a
93 non-letter. These sequences are reserved for major modes.
95 Changing all the major modes in Emacs 18 so they would follow this
96 convention was a lot of work. Abandoning this convention would waste
97 that work and inconvenience the users.
100 You should not bind @kbd{C-h} following any prefix character (including
101 @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
102 as a help character for listing the subcommands of the prefix character.
105 You should not bind a key sequence ending in @key{ESC} except following
106 another @key{ESC}. (That is, it is ok to bind a sequence ending in
107 @kbd{@key{ESC} @key{ESC}}.)
109 The reason for this rule is that a non-prefix binding for @key{ESC} in
110 any context prevents recognition of escape sequences as function keys in
114 Applications should not bind mouse events based on button 1 with the
115 shift key held down. These events include @kbd{S-mouse-1},
116 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
120 Modes should redefine @kbd{mouse-2} as a command to follow some sort of
121 reference in the text of a buffer, if users usually would not want to
122 alter the text in that buffer by hand. Modes such as Dired, Info,
123 Compilation, and Occur redefine it in this way.
126 When a package provides a modification of ordinary Emacs behavior, it is
127 good to include a command to enable and disable the feature, Provide a
128 command named @code{@var{whatever}-mode} which turns the feature on or
129 off, and make it autoload (@pxref{Autoload}). Design the package so
130 that simply loading it has no visible effect---that should not enable
131 the feature. Users will request the feature by invoking the command.
134 It is a bad idea to define aliases for the Emacs primitives. Use the
135 standard names instead.
138 Redefining an Emacs primitive is an even worse idea.
139 It may do the right thing for a particular program, but
140 there is no telling what other programs might break as a result.
143 If a file does replace any of the functions or library programs of
144 standard Emacs, prominent comments at the beginning of the file should
145 say which functions are replaced, and how the behavior of the
146 replacements differs from that of the originals.
149 If a file requires certain standard library programs to be loaded
150 beforehand, then the comments at the beginning of the file should say
154 Please keep the names of your Emacs Lisp source files to 13 characters
155 or less. This way, if the files are compiled, the compiled files' names
156 will be 14 characters or less, which is short enough to fit on all kinds
160 Don't use @code{next-line} or @code{previous-line} in programs; nearly
161 always, @code{forward-line} is more convenient as well as more
162 predictable and robust. @xref{Text Lines}.
165 Don't call functions that set the mark, unless setting the mark is one
166 of the intended features of your program. The mark is a user-level
167 feature, so it is incorrect to change the mark except to supply a value
168 for the user's benefit. @xref{The Mark}.
170 In particular, don't use these functions:
174 @code{beginning-of-buffer}, @code{end-of-buffer}
176 @code{replace-string}, @code{replace-regexp}
179 If you just want to move point, or replace a certain string, without any
180 of the other features intended for interactive users, you can replace
181 these functions with one or two lines of simple Lisp code.
184 Use lists rather than vectors, except when there is a particular reason
185 to use a vector. Lisp has more facilities for manipulating lists than
186 for vectors, and working with lists is usually more convenient.
188 Vectors are advantageous for tables that are substantial in size and are
189 accessed in random order (not searched front to back), provided there is
190 no need to insert or delete elements (only lists allow that).
193 The recommended way to print a message in the echo area is with
194 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
197 When you encounter an error condition, call the function @code{error}
198 (or @code{signal}). The function @code{error} does not return.
199 @xref{Signaling Errors}.
201 Do not use @code{message}, @code{throw}, @code{sleep-for},
202 or @code{beep} to report errors.
205 Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
206 command does: use a new local keymap that contains one command defined
207 to switch back to the old local keymap. Or do what the
208 @code{edit-options} command does: switch to another buffer and let the
209 user switch back at will. @xref{Recursive Editing}.
212 In some other systems there is a convention of choosing variable names
213 that begin and end with @samp{*}. We don't use that convention in Emacs
214 Lisp, so please don't use it in your programs. (Emacs uses such names
215 only for program-generated buffers.) The users will find Emacs more
216 coherent if all libraries use the same conventions.
219 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
220 default indentation parameters.
223 Don't make a habit of putting close-parentheses on lines by themselves;
224 Lisp programmers find this disconcerting. Once in a while, when there
225 is a sequence of many consecutive close-parentheses, it may make sense
226 to split them in one or two significant places.
229 Please put a copyright notice on the file if you give copies to anyone.
230 Use the same lines that appear at the top of the Lisp files in Emacs
231 itself. If you have not signed papers to assign the copyright to the
232 Foundation, then place your name in the copyright notice in place of the
236 @node Compilation Tips
237 @section Tips for Making Compiled Code Fast
238 @cindex execution speed
241 Here are ways of improving the execution speed of byte-compiled
247 @cindex timing programs
248 @cindex @file{profile.el}
249 Use the @file{profile} library to profile your program. See the file
250 @file{profile.el} for instructions.
253 Use iteration rather than recursion whenever possible.
254 Function calls are slow in Emacs Lisp even when a compiled function
255 is calling another compiled function.
258 Using the primitive list-searching functions @code{memq}, @code{assq}, or
259 @code{assoc} is even faster than explicit iteration. It may be worth
260 rearranging a data structure so that one of these primitive search
261 functions can be used.
264 Certain built-in functions are handled specially in byte-compiled code,
265 avoiding the need for an ordinary function call. It is a good idea to
266 use these functions rather than alternatives. To see whether a function
267 is handled specially by the compiler, examine its @code{byte-compile}
268 property. If the property is non-@code{nil}, then the function is
271 For example, the following input will show you that @code{aref} is
272 compiled specially (@pxref{Array Functions}) while @code{elt} is not
273 (@pxref{Sequence Functions}):
277 (get 'aref 'byte-compile)
278 @result{} byte-compile-two-args
282 (get 'elt 'byte-compile)
288 If calling a small function accounts for a substantial part of your
289 program's running time, make the function inline. This eliminates
290 the function call overhead. Since making a function inline reduces
291 the flexibility of changing the program, don't do it unless it gives
292 a noticeable speedup in something slow enough that users care about
293 the speed. @xref{Inline Functions}.
296 @node Documentation Tips
297 @section Tips for Documentation Strings
299 Here are some tips for the writing of documentation strings.
303 Every command, function, or variable intended for users to know about
304 should have a documentation string.
307 An internal subroutine of a Lisp program need not have a documentation
308 string, and you can save space by using a comment instead.
311 The first line of the documentation string should consist of one or two
312 complete sentences that stand on their own as a summary. @kbd{M-x
313 apropos} displays just the first line, and if it doesn't stand on its
314 own, the result looks bad. In particular, start the first line with a
315 capital letter and end with a period.
317 The documentation string can have additional lines that expand on the
318 details of how to use the function or variable. The additional lines
319 should be made up of complete sentences also, but they may be filled if
323 For consistency, phrase the verb in the first sentence of a
324 documentation string as an infinitive with ``to'' omitted. For
325 instance, use ``Return the cons of A and B.'' in preference to ``Returns
326 the cons of A and B@.'' Usually it looks good to do likewise for the
327 rest of the first paragraph. Subsequent paragraphs usually look better
328 if they have proper subjects.
331 Write documentation strings in the active voice, not the passive, and in
332 the present tense, not the future. For instance, use ``Return a list
333 containing A and B.'' instead of ``A list containing A and B will be
337 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
338 Instead of, ``Cause Emacs to display text in boldface,'' write just
339 ``Display text in boldface.''
342 Do not start or end a documentation string with whitespace.
345 Format the documentation string so that it fits in an Emacs window on an
346 80-column screen. It is a good idea for most lines to be no wider than
347 60 characters. The first line can be wider if necessary to fit the
348 information that ought to be there.
350 However, rather than simply filling the entire documentation string, you
351 can make it much more readable by choosing line breaks with care.
352 Use blank lines between topics if the documentation string is long.
355 @strong{Do not} indent subsequent lines of a documentation string so
356 that the text is lined up in the source code with the text of the first
357 line. This looks nice in the source code, but looks bizarre when users
358 view the documentation. Remember that the indentation before the
359 starting double-quote is not part of the string!
362 A variable's documentation string should start with @samp{*} if the
363 variable is one that users would often want to set interactively. If
364 the value is a long list, or a function, or if the variable would be set
365 only in init files, then don't start the documentation string with
366 @samp{*}. @xref{Defining Variables}.
369 The documentation string for a variable that is a yes-or-no flag should
370 start with words such as ``Non-nil means@dots{}'', to make it clear that
371 all non-@code{nil} values are equivalent and indicate explicitly what
372 @code{nil} and non-@code{nil} mean.
375 When a function's documentation string mentions the value of an argument
376 of the function, use the argument name in capital letters as if it were
377 a name for that value. Thus, the documentation string of the function
378 @code{/} refers to its second argument as @samp{DIVISOR}, because the
379 actual argument name is @code{divisor}.
381 Also use all caps for meta-syntactic variables, such as when you show
382 the decomposition of a list or vector into subunits, some of which may
387 When a documentation string refers to a Lisp symbol, write it as it
388 would be printed (which usually means in lower case), with single-quotes
389 around it. For example: @samp{`lambda'}. There are two exceptions:
390 write @code{t} and @code{nil} without single-quotes.
393 When a documentation string refers to a Lisp symbol, write it as it
394 would be printed (which usually means in lower case), with single-quotes
395 around it. For example: @samp{lambda}. There are two exceptions: write
396 t and nil without single-quotes. (In this manual, we normally do use
397 single-quotes for those symbols.)
401 Don't write key sequences directly in documentation strings. Instead,
402 use the @samp{\\[@dots{}]} construct to stand for them. For example,
403 instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When
404 Emacs displays the documentation string, it substitutes whatever key is
405 currently bound to @code{forward-char}. (This is normally @samp{C-f},
406 but it may be some other character if the user has moved key bindings.)
407 @xref{Keys in Documentation}.
410 In documentation strings for a major mode, you will want to refer to the
411 key bindings of that mode's local map, rather than global ones.
412 Therefore, use the construct @samp{\\<@dots{}>} once in the
413 documentation string to specify which key map to use. Do this before
414 the first use of @samp{\\[@dots{}]}. The text inside the
415 @samp{\\<@dots{}>} should be the name of the variable containing the
416 local keymap for the major mode.
418 It is not practical to use @samp{\\[@dots{}]} very many times, because
419 display of the documentation string will become slow. So use this to
420 describe the most important commands in your major mode, and then use
421 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
424 Don't use the term ``Elisp'', since that is or was a trademark.
425 Use the term ``Emacs Lisp''.
429 @section Tips on Writing Comments
431 We recommend these conventions for where to put comments and how to
436 Comments that start with a single semicolon, @samp{;}, should all be
437 aligned to the same column on the right of the source code. Such
438 comments usually explain how the code on the same line does its job. In
439 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
440 command automatically inserts such a @samp{;} in the right place, or
441 aligns such a comment if it is already present.
443 This and following examples are taken from the Emacs sources.
447 (setq base-version-list ; there was a base
448 (assoc (substring fn 0 start-vn) ; version to which
449 file-version-assoc-list)) ; this looks like
455 Comments that start with two semicolons, @samp{;;}, should be aligned to
456 the same level of indentation as the code. Such comments usually
457 describe the purpose of the following lines or the state of the program
458 at that point. For example:
462 (prog1 (setq auto-fill-function
466 (force-mode-line-update)))
470 Every function that has no documentation string (because it is use only
471 internally within the package it belongs to), should have instead a
472 two-semicolon comment right before the function, explaining what the
473 function does and how to call it properly. Explain precisely what each
474 argument means and how the function interprets its possible values.
477 Comments that start with three semicolons, @samp{;;;}, should start at
478 the left margin. Such comments are used outside function definitions to
479 make general statements explaining the design principles of the program.
484 ;;; This Lisp code is run in Emacs
485 ;;; when it is to operate as a server
486 ;;; for other processes.
490 Another use for triple-semicolon comments is for commenting out lines
491 within a function. We use triple-semicolons for this precisely so that
492 they remain at the left margin.
496 ;;; This is no longer necessary.
497 ;;; (force-mode-line-update)
498 (message "Finished with %s" a))
502 Comments that start with four semicolons, @samp{;;;;}, should be aligned
503 to the left margin and are used for headings of major sections of a
504 program. For example:
512 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
513 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
514 automatically indent comments according to these conventions,
515 depending on the number of semicolons. @xref{Comments,,
516 Manipulating Comments, emacs, The GNU Emacs Manual}.
518 @node Library Headers
519 @section Conventional Headers for Emacs Libraries
520 @cindex header comments
521 @cindex library header comments
523 Emacs 19 has conventions for using special comments in Lisp libraries
524 to divide them into sections and give information such as who wrote
525 them. This section explains these conventions. First, an example:
529 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
531 ;; Copyright (C) 1992 Free Software Foundation, Inc.
534 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
535 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
536 ;; Created: 14 Jul 1992
541 ;; This file is part of GNU Emacs.
542 @var{copying permissions}@dots{}
546 The very first line should have this format:
549 ;;; @var{filename} --- @var{description}
553 The description should be complete in one line.
555 After the copyright notice come several @dfn{header comment} lines,
556 each beginning with @samp{;; @var{header-name}:}. Here is a table of
557 the conventional possibilities for @var{header-name}:
561 This line states the name and net address of at least the principal
562 author of the library.
564 If there are multiple authors, you can list them on continuation lines
565 led by @code{;;} and a tab character, like this:
569 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
570 ;; Dave Sill <de5@@ornl.gov>
571 ;; Dave Brennan <brennan@@hal.com>
572 ;; Eric Raymond <esr@@snark.thyrsus.com>
577 This line should contain a single name/address as in the Author line, or
578 an address only, or the string @samp{FSF}. If there is no maintainer
579 line, the person(s) in the Author field are presumed to be the
580 maintainers. The example above is mildly bogus because the maintainer
583 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
584 possible a Lisp function to ``send mail to the maintainer'' without
585 having to mine the name out by hand.
587 Be sure to surround the network address with @samp{<@dots{}>} if
588 you include the person's full name as well as the network address.
591 This optional line gives the original creation date of the
592 file. For historical interest only.
595 If you wish to record version numbers for the individual Lisp program, put
599 In this header line, place the name of the person who adapted the
600 library for installation (to make it fit the style conventions, for
604 This line lists keywords for the @code{finder-by-keyword} help command.
605 This field is important; it's how people will find your package when
606 they're looking for things by topic area.
609 Just about every Lisp library ought to have the @samp{Author} and
610 @samp{Keywords} header comment lines. Use the others if they are
611 appropriate. You can also put in header lines with other header
612 names---they have no standard meanings, so they can't do any harm.
614 We use additional stylized comments to subdivide the contents of the
615 library file. Here is a table of them:
618 @item ;;; Commentary:
619 This begins introductory comments that explain how the library works.
620 It should come right after the copying permissions.
622 @item ;;; Change log:
623 This begins change log information stored in the library file (if you
624 store the change history there). For most of the Lisp
625 files distributed with Emacs, the change history is kept in the file
626 @file{ChangeLog} and not in the source file at all; these files do
627 not have a @samp{;;; Change log:} line.
630 This begins the actual code of the program.
632 @item ;;; @var{filename} ends here
633 This is the @dfn{footer line}; it appears at the very end of the file.
634 Its purpose is to enable people to detect truncated versions of the file
635 from the lack of a footer line.