2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c Copyright (C) 2005, 2006 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/tips.info
8 @node Tips, Building SXEmacs and Object Allocation, MULE, Top
9 @appendix Tips and Standards
11 @cindex standards of coding style
12 @cindex coding standards
14 This chapter describes no additional features of SXEmacs Lisp.
15 Instead it gives advice on making effective use of the features described
16 in the previous chapters.
19 * Style Tips:: Writing clean and robust programs.
20 * Performance Tips:: How to write efficient lisp code.
21 * Compatibility Tips:: How to write compatible lisp code.
22 * Documentation Tips:: Writing readable documentation strings.
23 * Comment Tips:: Conventions for writing comments.
24 * Library Headers:: Standard headers for library packages.
29 @section Writing Clean Lisp Programs
31 Here are some tips for avoiding common errors in writing Lisp code
32 intended for widespread use:
36 Since all global variables share the same name space, and all functions
37 share another name space, you should choose a short word to distinguish
38 your program from other Lisp programs. Then take care to begin the
39 names of all global variables, constants, and functions with the chosen
40 prefix. This helps avoid name conflicts.
42 This recommendation applies even to names for traditional Lisp
43 primitives that are not primitives in SXEmacs Lisp---even to @code{cadr}.
44 Believe it or not, there is more than one plausible way to define
45 @code{cadr}. Play it safe; append your name prefix to produce a name
46 like @code{foo-cadr} or @code{mylib-cadr} instead.
48 If you write a function that you think ought to be added to SXEmacs under
49 a certain name, such as @code{twiddle-files}, do not call it by that name
50 in your program. Call it @code{mylib-twiddle-files} in your program,
51 and send mail to @samp{sxemacs-devel@@sxemacs.org} suggesting we add
52 it to SXEmacs. If and when we do, we can change the name easily enough.
54 If one prefix is insufficient, your package may use two or three
55 alternative common prefixes, so long as they make sense.
57 Separate the prefix from the rest of the symbol name with a hyphen,
58 @samp{-}. This will be consistent with SXEmacs itself and with most
62 It is often useful to put a call to @code{provide} in each separate
63 library program, at least if there is more than one entry point to the
67 If a file requires certain other library programs to be loaded
68 beforehand, then the comments at the beginning of the file should say
69 so. Also, use @code{require} to make sure they are loaded.
72 If one file @var{foo} uses a macro defined in another file @var{bar},
73 @var{foo} should contain this expression before the first use of the
77 (eval-when-compile (require '@var{bar}))
81 And, of course, @var{bar} should contain @code{(provide '@var{bar})}, to
82 make the @code{require} work. This will cause @var{bar} to be loaded
83 when you byte-compile @var{foo}. Otherwise, you risk compiling
84 @var{foo} without the necessary macro loaded, and that would produce
85 compiled code that will not work right. @xref{Compiling Macros}.
87 Using @code{eval-when-compile} avoids loading @var{bar} when
88 the compiled version of @var{foo} is @emph{used}.
91 If you define a major mode, make sure to run a hook variable using
92 @code{run-hooks}, just as the existing major modes do. @xref{Hooks}.
95 If the purpose of a function is to tell you whether a certain condition
96 is true or false, give the function a name that ends in @samp{p}. If
97 the name is one word, add just @samp{p}; if the name is multiple words,
98 add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
101 If a user option variable records a true-or-false condition, give it a
102 name that ends in @samp{-flag}.
105 Please do not define @kbd{C-c @var{letter}} as a key in your major
106 modes. These sequences are reserved for users; they are the
107 @strong{only} sequences reserved for users, so we cannot do without
110 Instead, define sequences consisting of @kbd{C-c} followed by a
111 non-letter. These sequences are reserved for major modes.
113 Changing all the major modes in Emacs 18 so they would follow this
114 convention was a lot of work. Abandoning this convention would make
115 that work go to waste, and inconvenience users.
118 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
119 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
122 Sequences consisting of @kbd{C-c} followed by any other punctuation
123 character are allocated for minor modes. Using them in a major mode is
124 not absolutely prohibited, but if you do that, the major mode binding
125 may be shadowed from time to time by minor modes.
128 You should not bind @kbd{C-h} following any prefix character (including
129 @kbd{C-c}). If you do not bind @kbd{C-h}, it is automatically available
130 as a help character for listing the subcommands of the prefix character.
133 You should not bind a key sequence ending in @key{ESC} except following
134 another @key{ESC}. That is, it is ok to bind a sequence ending in
135 @kbd{@key{ESC} @key{ESC}}.
137 The reason for this rule is that a non-prefix binding for @key{ESC} in
138 any context prevents recognition of escape sequences as function keys in
142 Applications should not bind mouse events based on button 1 with the
143 shift key held down. These events include @kbd{S-mouse-1},
144 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
148 Modes should redefine @kbd{mouse-2} as a command to follow some sort of
149 reference in the text of a buffer, if users usually would not want to
150 alter the text in that buffer by hand. Modes such as Dired, Info,
151 Compilation, and Occur redefine it in this way.
154 When a package provides a modification of ordinary SXEmacs behavior, it
155 is good to include a command to enable and disable the feature, Provide
156 a command named @code{@var{whatever}-mode} which turns the feature on or
157 off, and make it autoload (@pxref{Autoload}). Design the package so
158 that simply loading it has no visible effect---that should not enable
159 the feature. Users will request the feature by invoking the command.
162 It is a bad idea to define aliases for the SXEmacs primitives. Use the
163 standard names instead.
166 Redefining a SXEmacs primitive is an even worse idea.
167 It may do the right thing for a particular program, but
168 there is no telling what other programs might break as a result.
171 If a file does replace any of the functions or library programs of
172 standard SXEmacs, prominent comments at the beginning of the file should
173 say which functions are replaced, and how the behavior of the
174 replacements differs from that of the originals.
177 Please keep the names of your SXEmacs Lisp source files to 13 characters
178 or less. This way, if the files are compiled, the compiled files' names
179 will be 14 characters or less, which is short enough to fit on all kinds
183 Do not use @code{next-line} or @code{previous-line} in programs; nearly
184 always, @code{forward-line} is more convenient as well as more
185 predictable and robust. @xref{Text Lines}.
188 Do not call functions that set the mark, unless setting the mark is one
189 of the intended features of your program. The mark is a user-level
190 feature, so it is incorrect to change the mark except to supply a value
191 for the user's benefit. @xref{The Mark}.
193 In particular, do not use these functions:
197 @code{beginning-of-buffer}, @code{end-of-buffer}
199 @code{replace-string}, @code{replace-regexp}
202 If you just want to move point, or replace a certain string, without any
203 of the other features intended for interactive users, you can replace
204 these functions with one or two lines of simple Lisp code.
207 Use lists rather than vectors, except when there is a particular reason
208 to use a vector. Lisp has more facilities for manipulating lists than
209 for vectors, and working with lists is usually more convenient.
211 Vectors are advantageous for tables that are substantial in size and are
212 accessed in random order (not searched front to back), provided there is
213 no need to insert or delete elements (only lists allow that).
216 The recommended way to print a message in the echo area is with
217 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
220 When you encounter an error condition, call the function @code{error}
221 (or @code{signal}). The function @code{error} does not return.
222 @xref{Signaling Errors}.
224 Do not use @code{message}, @code{throw}, @code{sleep-for},
225 or @code{beep} to report errors.
228 An error message should start with a capital letter but should not end
232 Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
233 command does: use a new local keymap that contains one command defined
234 to switch back to the old local keymap. Or do what the
235 @code{edit-options} command does: switch to another buffer and let the
236 user switch back at will. @xref{Recursive Editing}.
239 In some other systems there is a convention of choosing variable names
240 that begin and end with @samp{*}. We do not use that convention in
241 SXEmacs Lisp, so please don't use it in your programs. Emacs uses such
242 names only for program-generated buffers. The users will find Emacs
243 more coherent if all libraries use the same conventions.
246 Use names starting with a space for temporary buffers (@pxref{Buffer
247 Names}), or at least call @code{buffer-disable-undo} on them. Otherwise
248 they may stay referenced by internal undo variables after getting
249 killed. If this happens before dumping (@pxref{Building SXEmacs}), this
250 may cause fatal error when portable dumper is used.
253 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
254 default indentation parameters.
257 Do not make a habit of putting close-parentheses on lines by themselves;
258 Lisp programmers find this disconcerting. Once in a while, when there
259 is a sequence of many consecutive close-parentheses, it may make sense
260 to split them in one or two significant places.
263 Please put a copyright notice on the file if you give copies to anyone.
264 Use the same lines that appear at the top of the Lisp files in SXEmacs
270 @node Performance Tips
271 @section Tips for efficient lisp code
272 @cindex execution speed
277 Here are ways of improving the execution speed of Lisp programs.
281 Use byte compilation whenever you can.
283 Beside the static byte compilation yielding @file{.elc} files, you can
284 also use the @code{byte-compile} function to create and use compiled
289 ;; @r{We create a byte compiled predicate and bind it to the variable}
290 ;; @r{@code{is-minus-one-p}.}
291 ;; @r{Note that we do _NOT_ create a function @code{is-minus-one-p}.}
294 #'(lambda (a) (zerop (1+ a)))))
295 @result{} #<compiled-function (a) "...(5)" [a zerop] 2>
299 ;; @r{We use the compiled function object of @code{is-minus-one-p}.}
301 (some is-minus-one-p '(1 2 3 4 -1))
307 Certain built-in functions are handled specially in byte-compiled code,
308 avoiding the need for an ordinary function call. It is a good idea to
309 use these functions rather than alternatives. To see whether a function
310 is handled specially by the compiler, examine its @code{byte-compile}
311 property. If the property is non-@code{nil}, then the function is
314 For example, the following input will show you that @code{aref} is
315 compiled specially (@pxref{Array Functions}) while @code{assoc} is not
316 (@pxref{Sequence Functions}):
320 (get 'aref 'byte-compile)
321 @result{} byte-compile-two-args
325 (get 'assoc 'byte-compile)
331 Teach yourself to tag functions with the special quote @code{function}
332 (short form is @code{#'}) instead of using an ordinary @code{quote}
333 (short @code{'}). In byte compilation, the byte-compiler will look
334 for function quotes and compile them. Ordinarily quoted function
335 names will not be investigated nor byte compiled.
337 The same applies to anonymous function objects (lambda lists) in
338 non-obvious forms like backquoted macro bodies, or @code{fset}
339 constructions in macros of the form @code{(list 'lambda argname
342 On the other hand, if cheating the byte compiler is explicitly what
343 you want emacs lisp will also accept the normal @code{quote} to refer
344 to the function cell in most cases.
347 If calling a small function accounts for a substantial part of your
348 program's running time, make the function inline (use @code{defsubst}.
349 This eliminates the function call overhead. Since making a function
350 inline reduces the flexibility of changing the program, do not do it
351 unless it gives a noticeable speedup in something slow enough that
352 users care about the speed. @xref{Inline Functions}.
354 @c these are more general tips
356 @cindex iteration vs. recursion
357 @cindex recursion vs. iteration
358 Use iteration rather than recursion whenever possible.
359 Function calls are slow in SXEmacs Lisp even when a compiled function
360 is calling another compiled function.
363 Using the primitive list-searching functions @code{memq}, @code{member},
364 @code{assq}, or @code{assoc} is even faster than explicit iteration. It
365 may be worth rearranging a data structure so that one of these primitive
366 search functions can be used.
370 @cindex timing programs
371 @cindex @file{profile.el}
372 Use the @file{profile} library to profile your program. See the file
373 @file{profile.el} for instructions.
376 If absolute performance timings are of interest do not use profile.el
377 since it redefines the investigated functions and hence slows down
378 their execution. With a minimal overhead you can use the
379 @code{current-btime} function to obtain an absolute time stamp with a
380 microsecond resolution.
383 For example we measure the execution time of @code{nreverse} for a
384 list of 1000 random numbers.
388 ;; @r{initialise the list}
391 (setq lrn (cons (random) lrn)))
392 @result{} @strong{omitted}
396 ;; @r{We use two time variables start and end.}
398 (setq start (current-btime))
399 (setq lrn (nreverse lrn))
400 (setq end (current-btime)))
404 ;; @r{We investigate the time by simply subtracting start from end.}
408 ;; @r{This means @code{nreverse} took about 190 microseconds.}
412 ;; @r{The real value is highly likely a little less than this.}
413 ;; @r{Let's measure the overhead.}
415 (setq start (current-btime))
416 (setq end (current-btime))
423 Deliberate about your data representation.
425 SXEmacs provides a multiplicity of types and containers to store your
426 data. Which of them suits your purpose best depends on many things
429 Do you want to be compatible to other Emacs flavours?
431 Well, in this case you should definitely have a glance at the flavour
432 you want to be compatible with. Also @pxref{Compatibility Tips}.
434 If compatibility is not an issue, you can benefit in many cases from
435 the large variety of dedicated data types in SXEmacs. See next item.
438 Do you want speed or comfort or flexibility or memory frugality?
444 @c Speed - derived from the time complexity
445 @c Comfort - derived from the number of supporter functions or the
447 @c Flexi - derived from the number and costs of prerequisites which
449 @c Memory - derived from the space complexity
456 @c operation speed comfort flexibility memory frugality
457 @c creation ++ ++ ++ ++
458 @c prepend ++ + ++ ++
466 @c operation speed comfort flexibility memory frugality
467 @c creation ++ - ++ +
468 @c prepend ++ - ++ ++
470 @c search n/a n/a -- n/a
471 @c modify n/a n/a -- n/a
472 @c sort n/a n/a -- n/a
476 @c operation speed comfort flexibility memory frugality
478 @c prepend ++ -- - --
479 @c append ++ -- ++ --
487 Consider external tools. But think first!
489 In some cases it is simply appropriate to use external tools. For
490 example it does not make sense to re-implement the block zipping
491 algorithm of bzip2 in elisp, instead create a process and call the
494 However, if external tools provide a shared object library the
495 process approach will highly likely be a snail compared to an FFI
496 implementation. The advantage is simply that FFI calls will not
497 create that much overhead because the available data is simply reused
498 and does not need further steps, e.g. preparing the input data for the
499 external tool, or parsing the results and converting them to lisp
502 Again, think twice! An FFI implementation can waste a large amount of
503 development time. Moreover, it requires a detailed knowledge of the
504 internal concept of the external resource. It is very easy to crash
505 your SXEmacs with FFI!
507 A safer way of using external libraries in the way FFI does is to
508 create an emodule. In very time critical scenarios, emodules may even
509 outperform FFI because large parts of a procedure can run at C level
510 without interacting with the lisp engine at all. You can even use all
511 the usual advantages of C, such as parallelism, multi-threading and
512 similar. Moreover, if desired you can wrap intermediate results to
513 special containers (using @code{dynacat}s), and pass these to the lisp
514 level. Indeed, @code{dynacat}s which escaped to the lisp level
515 are safe since there is no way to access or modify them. Of course,
516 you can envisage dedicated interface functions within your emodule
517 but even in that case the actual processing will always take place in
518 your emodule at C level.
520 Anyway, emodules suffer from a serious drawback: they have to be built
521 first in order to use them. In contrast, both the process approach
522 and the FFI implementation just work out of the box.
528 @node Compatibility Tips
529 @section Tips for writing compatible code
531 Writing compatible code is very easy whenever a problem is decoupled
532 enough. That is when your problem is of abstract nature and does not
533 explicitly depend on a certain OS, emacs flavour, external tools, or
536 In that case you would simply divide your code in two parts, the
537 abstract layer which contains the solution of your problem in an
538 abstract (read independent) way, and the implementation layer which
539 contains OS specific, flavour specific, tool specific and/or file
540 system layout specific implementations and which thus provides one or
541 more interfaces for your abstract layer.
543 Fine, so why are there so many problems between, say, code for FSF
544 Emacs and (S)XEmacs? Well, programmers are not always professional
545 software designers. Also, compatibility often plays a minor role,
546 especially in young projects or projects with little man power. But
547 the most understandable reason might be that one or more pieces of
548 code simply cannot be decoupled or at least not in an efficient way.
550 Anyway, let us look at very simple compatibility issues. The most
551 trivial case of course is a problem independent from all of the
552 aforementioned requisites, like sorting a list of numbers
553 ascendingly. This can be done using only an iteration function (like
554 @code{while}), assignment operators (@code{setq}), a predicate
555 (@code{<}) and the list primitives @code{cons}, @code{car},
556 @code{cdr}. All of these routines are available in any emacs on any
557 OS. Hence compatibility is not an issue.
559 Nonetheless, even such a simple thing can be transformed into a
560 broadly incompatible mess. Just assume that programmers choose the
561 way with least obstacles -- some people prefer the term lazy though --
562 they will definitely use a primitive like @code{sort},
563 @code{stable-sort} or @code{sort*}. Or assume that sorting numbers is
564 just a small subproblem of a larger one and the context stipulates
565 that numbers must be arranged in vectors instead of lists. In such
566 cases consider the following small checklist.
570 Are all the constructors, modifiers and predicates defined?
572 Conditionalise with @code{fboundp} and @code{boundp} constructions
575 (when (fboundp #'make-hash-table)
581 (when (featurep 'sxemacs)
585 or operating systems, e.g.:
587 (when (eq system-type 'linux)
592 Do they behave as expected?
594 Check for number, order and type of the arguments. If feasible write
595 a small, simple testcase, like
597 (hash-table-p (make-hash-table :size 120 :test #'eq))
600 In order to use this sort of test within your code, for example to
601 trigger an implementation based on the success, you could use the
602 @code{condition-case} construction:
607 (hash-table-p (make-hash-table :size 120 :test #'eq))
609 (error nil)) ;; return `nil' in case of error
615 Does your code depend on other elisp libraries or packages?
616 Perhaps not even distributed ones?
618 If feasible consider distributing a compatibility layer (see below).
619 In this case, you must decouple your code such that it can either use
620 the native implementation or the one provided by your compatibility
623 If reinventing the wheel is not an issue, consider distributing the
624 foreign requisites along with your code. This implies of course that
625 you carefully checked the foreign resources for their compatibility.
626 Also, make sure that the licences permit your decision.
628 In case there are too many requisite libraries to stuff them all into
629 your package, or if licences forbid this, you should definitely give
630 your users a notice, preferrably with detailed instructions on how to
631 resolve the dependencies, at least include a location where users can
632 fetch a known-to-work version.
635 Does your code depend on external, perhaps OS specific resources, like
636 ssh, apache, C compilers, shared libraries, special hardware and
639 This is probably the hardest case and there is definitely no patent
640 remedy. If you cannot grant compatibility or detect missing
641 necessities for a specific target, you must at least notify your users
644 If you know other code or projects which manage the situation `better'
645 than you (i.e. with less requisites or better/native support) name
646 those alternatives. If you do not know alternatives or other
647 approaches seem to far away from your own it is definitely a good idea
648 to explain in @strong{great} detail what you are trying to do. This
649 way users get the chance to look for alternatives themselves.
654 @subsection How to write a compatibility layer
655 @cindex compatibility layer
657 There is no generic approach to do that. However, there is a general
658 idea which has been mentioned already in the introduction. Decouple
659 your program so much that you do not call any functions, macros or
660 variables which are suspicious to be incompatible.
662 Let us work out this idea in a practical scenario. Imagine you have
663 to deal with aspect ratios as they occur in image data or video
664 material, e.g. 16:9, 16:10 or the like. Now initial research reveals
665 that both XEmacs 21.5.x and SXEmacs may provide built-in support for
666 rational quotients, whereas XEmacs 21.4.x and GNU Emacs do not.
668 Now since we know that we only want to multiply fractions with
669 integers, we merely provide this single operation, along with a
670 constructor, a predicate and two accessors. Note, we will put the
671 detection code along with the two implementations in the following
672 example. In practice each implementation usually occupies a file of
673 its own and the detection resides at a central location, for example
674 in the library's main file.
678 ;; check if SXEmacs is build with ENT support (bigq submodule)
679 (and (featurep 'ent) (featurep 'bigq))
681 ;; the constructor (takes two arguments, two rational integers)
682 (defalias 'expkg-make-quotient #'//)
683 ;; the predicate (takes one argument, a bigq)
684 (defalias 'expkg-quotient-p #'bigqp)
686 ;; an accessor for the numerator of a quotient (takes a bigq)
687 (defalias 'expkg-quotient-num #'numerator)
688 ;; an accessor for the denominator of a quotient (takes a bigq)
689 (defalias 'expkg-quotient-den #'denominator)
691 ;; a * function for quotients by integers
692 (defalias 'expkg-mult-quo-int #'*))
695 ;; or is it XEmacs with ratio support? SXE says `t', too, so check
697 (and (not (featurep 'sxemacs)) (featurep 'ratio))
699 (defalias 'expkg-make-quotient #'div)
700 (defalias 'expkg-quotient-p #'ratiop)
702 (defalias 'expkg-quotient-num #'numerator)
703 (defalias 'expkg-quotient-den #'denominator)
705 (defalias 'expkg-mult-quo-int #'*))
707 ;; just check if expkg-make-quotient is bound already
708 (unless (fboundp #'expkg-make-quotient)
711 (defun expkg-make-quotient (numerator denominator)
712 "Return the quotient numerator/denominator"
713 ;; we choose to store in a 3 component vector
714 (vector 'quotient numerator denominator))
717 (defun expkg-quotient-p (object)
718 "Return `t' if OBJECT is a quotient."
719 ;; we check for the vector property, if length equals 3 and
720 ;; finally if our indicator is present
721 (and (vectorp object)
722 (= (length object) 3)
723 (eq (aref object 0) 'quotient)))
726 (defun expkg-quotient-num (quotient)
727 "Return the numerator of QUOTIENT."
728 ;; check if QUOTIENT is indeed what we expect
729 (if (expkg-quotient-p quotient)
731 (error "Wrong type argument, quotientp `%s'" quotient)))
734 (defun expkg-quotient-den (quotient)
735 "Return the denominator of QUOTIENT."
736 ;; check if QUOTIENT is indeed what we expect
737 (if (expkg-quotient-p quotient)
739 (error "Wrong type argument, quotientp `%s'" quotient)))
742 (defun expkg-mult-quo-int (quo int)
743 "Return the product of QUO with INT."
744 (if (and (expkg-quotient-p quo)
747 ;; new-num <- num * int
748 (* (expkg-quotient-num quo) int)
750 (expkg-quotient-den quo))
752 (error "Wrong type argument, quotientp `%s', integerp `%s'"
756 Now that's it! Now we can use the functions defined here to interface
757 the quotient functionality in an abstract way. Moreover, this example
758 demonstrates how to decouple a concept (quotients in this case) from
759 the actual data type used to represent the concept, in order of
760 appearance quotients can be represented as bigqs, as ratios or as
763 However, as you may have noticed not all internals can be abstracted
764 in a sane way. In our case, the abstract layer will make up quotients
765 of integers. We simply assumed -- or knew -- that these exist in all
766 emacs flavours and behave identically.
770 @node Documentation Tips
771 @section Tips for Documentation Strings
773 Here are some tips for the writing of documentation strings.
777 Every command, function, or variable intended for users to know about
778 should have a documentation string.
781 An internal variable or subroutine of a Lisp program might as well have
782 a documentation string. In earlier Emacs versions, you could save space
783 by using a comment instead of a documentation string, but that is no
787 The first line of the documentation string should consist of one or two
788 complete sentences that stand on their own as a summary. @kbd{M-x
789 apropos} displays just the first line, and if it doesn't stand on its
790 own, the result looks bad. In particular, start the first line with a
791 capital letter and end with a period.
793 The documentation string can have additional lines that expand on the
794 details of how to use the function or variable. The additional lines
795 should be made up of complete sentences also, but they may be filled if
799 For consistency, phrase the verb in the first sentence of a
800 documentation string as an infinitive with ``to'' omitted. For
801 instance, use ``Return the cons of A and B.'' in preference to ``Returns
802 the cons of A and B@.'' Usually it looks good to do likewise for the
803 rest of the first paragraph. Subsequent paragraphs usually look better
804 if they have proper subjects.
807 Write documentation strings in the active voice, not the passive, and in
808 the present tense, not the future. For instance, use ``Return a list
809 containing A and B.'' instead of ``A list containing A and B will be
813 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
814 Instead of, ``Cause Emacs to display text in boldface,'' write just
815 ``Display text in boldface.''
818 Do not start or end a documentation string with whitespace.
821 Format the documentation string so that it fits in an Emacs window on an
822 80-column screen. It is a good idea for most lines to be no wider than
823 60 characters. The first line can be wider if necessary to fit the
824 information that ought to be there.
826 However, rather than simply filling the entire documentation string, you
827 can make it much more readable by choosing line breaks with care.
828 Use blank lines between topics if the documentation string is long.
831 @strong{Do not} indent subsequent lines of a documentation string so
832 that the text is lined up in the source code with the text of the first
833 line. This looks nice in the source code, but looks bizarre when users
834 view the documentation. Remember that the indentation before the
835 starting double-quote is not part of the string!
838 A variable's documentation string should start with @samp{*} if the
839 variable is one that users would often want to set interactively. If
840 the value is a long list, or a function, or if the variable would be set
841 only in init files, then don't start the documentation string with
842 @samp{*}. @xref{Defining Variables}.
845 The documentation string for a variable that is a yes-or-no flag should
846 start with words such as ``Non-nil means@dots{}'', to make it clear that
847 all non-@code{nil} values are equivalent and indicate explicitly what
848 @code{nil} and non-@code{nil} mean.
851 When a function's documentation string mentions the value of an argument
852 of the function, use the argument name in capital letters as if it were
853 a name for that value. Thus, the documentation string of the function
854 @code{/} refers to its second argument as @samp{DIVISOR}, because the
855 actual argument name is @code{divisor}.
857 Also use all caps for meta-syntactic variables, such as when you show
858 the decomposition of a list or vector into subunits, some of which may
863 When a documentation string refers to a Lisp symbol, write it as it
864 would be printed (which usually means in lower case), with single-quotes
865 around it. For example: @samp{`lambda'}. There are two exceptions:
866 write @code{t} and @code{nil} without single-quotes.
869 When a documentation string refers to a Lisp symbol, write it as it
870 would be printed (which usually means in lower case), with single-quotes
871 around it. For example: @samp{lambda}. There are two exceptions: write
872 t and nil without single-quotes. In this manual, we normally do use
873 single-quotes for those symbols.
877 Do not write key sequences directly in documentation strings. Instead,
878 use the @samp{\\[@dots{}]} construct to stand for them. For example,
879 instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When
880 SXEmacs displays the documentation string, it substitutes whatever key
881 is currently bound to @code{forward-char}. This is normally @samp{C-f},
882 but it may be some other character if the user has moved key bindings.
883 @xref{Keys in Documentation}.
886 In documentation strings for a major mode, you will want to refer to the
887 key bindings of that mode's local map, rather than global ones.
888 Therefore, use the construct @samp{\\<@dots{}>} once in the
889 documentation string to specify which key map to use.
891 Do this before the first use of @samp{\\[@dots{}]}. The text inside the
892 @samp{\\<@dots{}>} should be the name of the variable containing the
893 local keymap for the major mode.
895 It is not practical to use @samp{\\[@dots{}]} very many times, because
896 display of the documentation string will become slow. So use this to
897 describe the most important commands in your major mode, and then use
898 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
903 @section Tips on Writing Comments
905 We recommend these conventions for where to put comments and how to
910 Comments that start with a single semicolon, @samp{;}, should all be
911 aligned to the same column on the right of the source code. Such
912 comments usually explain how the code on the same line does its job.
914 In Lisp mode and related modes, the @kbd{M-;}
915 (@code{indent-for-comment}) command automatically inserts such a
916 @samp{;} in the right place, or aligns such a comment if it is already
919 This and following examples are taken from the SXEmacs sources.
923 (setq base-version-list ; there was a base
924 (assoc (substring fn 0 start-vn) ; version to which
925 file-version-assoc-list)) ; this looks like
931 Comments that start with two semicolons, @samp{;;}, should be aligned to
932 the same level of indentation as the code. Such comments usually
933 describe the purpose of the following lines or the state of the program
934 at that point. For example:
938 (prog1 (setq auto-fill-function
946 Every function that has no documentation string (because it is used only
947 internally within the package it belongs to), should have instead a
948 two-semicolon comment right before the function, explaining what the
949 function does and how to call it properly. Explain precisely what each
950 argument means and how the function interprets its possible values.
953 Comments that start with three semicolons, @samp{;;;}, should start at
954 the left margin. Such comments are used outside function definitions to
955 make general statements explaining the design principles of the program.
960 ;;; This Lisp code is run in SXEmacs
961 ;;; when it is to operate as a server
962 ;;; for other processes.
966 Another use for triple-semicolon comments is for commenting out lines
967 within a function. We use triple-semicolons for this precisely so that
968 they remain at the left margin.
972 ;;; This is no longer necessary.
973 ;;; (force-mode-line-update)
974 (message "Finished with %s" a))
978 Comments that start with four semicolons, @samp{;;;;}, should be aligned
979 to the left margin and are used for headings of major sections of a
980 program. For example:
988 The indentation commands of the Lisp modes in SXEmacs, such as @kbd{M-;}
989 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
990 automatically indent comments according to these conventions,
991 depending on the number of semicolons. @xref{Comments,,
992 Manipulating Comments, sxemacs, The SXEmacs User's Manual}.
995 @node Library Headers
996 @section Conventional Headers for XEmacs Libraries
997 @cindex header comments
998 @cindex library header comments
1000 SXEmacs has conventions for using special comments in Lisp libraries
1001 to divide them into sections and give information such as who wrote
1002 them. This section explains these conventions. First, an example:
1006 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
1008 ;; Copyright (C) 1992 Free Software Foundation, Inc.
1011 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
1012 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
1013 ;; Created: 14 Jul 1992
1018 ;; This file is part of SXEmacs.
1019 @var{copying permissions}@dots{}
1023 The very first line should have this format:
1026 ;;; @var{filename} --- @var{description}
1030 The description should be complete in one line.
1032 After the copyright notice come several @dfn{header comment} lines,
1033 each beginning with @samp{;; @var{header-name}:}. Here is a table of
1034 the conventional possibilities for @var{header-name}:
1038 This line states the name and net address of at least the principal
1039 author of the library.
1041 If there are multiple authors, you can list them on continuation lines
1042 led by @code{;;} and a tab character, like this:
1046 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
1047 ;; Dave Sill <de5@@ornl.gov>
1048 ;; Dave Brennan <brennan@@hal.com>
1049 ;; Eric Raymond <esr@@snark.thyrsus.com>
1054 This line should contain a single name/address as in the Author line, or
1055 an address only. If there is no maintainer line, the person(s) in the
1056 Author field are presumed to be the maintainers. The example above is
1057 mildly bogus because the maintainer line is redundant.
1059 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
1060 possible a Lisp function to ``send mail to the maintainer'' without
1061 having to mine the name out by hand.
1063 Be sure to surround the network address with @samp{<@dots{}>} if
1064 you include the person's full name as well as the network address.
1067 This optional line gives the original creation date of the
1068 file. For historical interest only.
1071 If you wish to record version numbers for the individual Lisp program, put
1075 In this header line, place the name of the person who adapted the
1076 library for installation (to make it fit the style conventions, for
1080 This line lists keywords for the @code{finder-by-keyword} help command.
1081 This field is important; it is how people will find your package when
1082 they're looking for things by topic area. To separate the keywords, you
1083 can use spaces, commas, or both.
1086 Just about every Lisp library ought to have the @samp{Author} and
1087 @samp{Keywords} header comment lines. Use the others if they are
1088 appropriate. You can also put in header lines with other header
1089 names---they have no standard meanings, so they can't do any harm.
1091 We use additional stylized comments to subdivide the contents of the
1092 library file. Here is a table of them:
1095 @item ;;; Commentary:
1096 This begins introductory comments that explain how the library works.
1097 It should come right after the copying permissions.
1099 @item ;;; Change log:
1100 This begins change log information stored in the library file (if you
1101 store the change history there). For most of the Lisp
1102 files distributed with SXEmacs, the change history is kept in the file
1103 @file{ChangeLog} or may be retrieved with the @code{tla changelog} shell
1104 command. They are not kept in the source file at all; these files do
1105 not have a @samp{;;; Change log:} line.
1108 This begins the actual code of the program.
1110 @item ;;; @var{filename} ends here
1111 This is the @dfn{footer line}; it appears at the very end of the file.
1112 Its purpose is to enable people to detect truncated versions of the file
1113 from the lack of a footer line.
1118 @c tips.texi ends here