2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/tips
7 @node Tips, GNU Emacs Internals, GPL, Top
8 @appendix Tips and Conventions
10 @cindex standards of coding style
11 @cindex coding standards
13 This chapter describes no additional features of Emacs Lisp. Instead
14 it gives advice on making effective use of the features described in the
15 previous chapters, and describes conventions Emacs Lisp programmers
18 You can automatically check some of the conventions described below by
19 running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
20 It cannot check all of the conventions, and not all the warnings it
21 gives necessarily correspond to problems, but it is worth examining them
25 * Coding Conventions:: Conventions for clean and robust programs.
26 * Compilation Tips:: Making compiled code run fast.
27 * Documentation Tips:: Writing readable documentation strings.
28 * Comment Tips:: Conventions for writing comments.
29 * Library Headers:: Standard headers for library packages.
32 @node Coding Conventions
33 @section Emacs Lisp Coding Conventions
35 Here are conventions that you should follow when writing Emacs Lisp
36 code intended for widespread use:
40 Since all global variables share the same name space, and all
41 functions share another name space, you should choose a short word to
42 distinguish your program from other Lisp programs.@footnote{The
43 benefits of a Common Lisp-style package system are considered not to
44 outweigh the costs.} Then take care to begin the names of all global
45 variables, constants, and functions in your program with the chosen
46 prefix. This helps avoid name conflicts.
48 This recommendation applies even to names for traditional Lisp
49 primitives that are not primitives in Emacs Lisp---such as
50 @code{copy-list}. Believe it or not, there is more than one plausible
51 way to define @code{copy-list}. Play it safe; append your name prefix
52 to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
55 If you write a function that you think ought to be added to Emacs under
56 a certain name, such as @code{twiddle-files}, don't call it by that name
57 in your program. Call it @code{mylib-twiddle-files} in your program,
58 and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
59 it to Emacs. If and when we do, we can change the name easily enough.
61 If one prefix is insufficient, your package may use two or three
62 alternative common prefixes, so long as they make sense.
64 Separate the prefix from the rest of the symbol name with a hyphen,
65 @samp{-}. This will be consistent with Emacs itself and with most Emacs
69 It is often useful to put a call to @code{provide} in each separate
70 library program, at least if there is more than one entry point to the
74 If a file requires certain other library programs to be loaded
75 beforehand, then the comments at the beginning of the file should say
76 so. Also, use @code{require} to make sure they are loaded.
79 If one file @var{foo} uses a macro defined in another file @var{bar},
80 @var{foo} should contain this expression before the first use of the
84 (eval-when-compile (require '@var{bar}))
88 (And the library @var{bar} should contain @code{(provide '@var{bar})},
89 to make the @code{require} work.) This will cause @var{bar} to be
90 loaded when you byte-compile @var{foo}. Otherwise, you risk compiling
91 @var{foo} without the necessary macro loaded, and that would produce
92 compiled code that won't work right. @xref{Compiling Macros}.
94 Using @code{eval-when-compile} avoids loading @var{bar} when
95 the compiled version of @var{foo} is @emph{used}.
98 Please don't require the @code{cl} package of Common Lisp extensions at
99 run time. Use of this package is optional, and it is not part of the
100 standard Emacs namespace. If your package loads @code{cl} at run time,
101 that could cause name clashes for users who don't use that package.
103 However, there is no problem with using the @code{cl} package at compile
104 time, with @code{(eval-when-compile (require 'cl))}.
107 When defining a major mode, please follow the major mode
108 conventions. @xref{Major Mode Conventions}.
111 When defining a minor mode, please follow the minor mode
112 conventions. @xref{Minor Mode Conventions}.
115 If the purpose of a function is to tell you whether a certain condition
116 is true or false, give the function a name that ends in @samp{p}. If
117 the name is one word, add just @samp{p}; if the name is multiple words,
118 add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
121 If a user option variable records a true-or-false condition, give it a
122 name that ends in @samp{-flag}.
125 If the purpose of a variable is to store a single function, give it a
126 name that ends in @samp{-function}. If the purpose of a variable is
127 to store a list of functions (i.e., the variable is a hook), please
128 follow the naming conventions for hooks. @xref{Hooks}.
131 @cindex reserved keys
132 @cindex keys, reserved
133 Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs.
134 Sequences consisting of @kbd{C-c} and a letter (either upper or lower
135 case) are reserved for users; they are the @strong{only} sequences
136 reserved for users, so do not block them.
138 Changing all the Emacs major modes to respect this convention was a
139 lot of work; abandoning this convention would make that work go to
140 waste, and inconvenience users. Please comply with it.
143 Function keys @key{F5} through @key{F9} without modifier keys are
144 also reserved for users to define.
147 Applications should not bind mouse events based on button 1 with the
148 shift key held down. These events include @kbd{S-mouse-1},
149 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
153 Sequences consisting of @kbd{C-c} followed by a control character or a
154 digit are reserved for major modes.
157 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
158 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
161 Sequences consisting of @kbd{C-c} followed by any other punctuation
162 character are allocated for minor modes. Using them in a major mode is
163 not absolutely prohibited, but if you do that, the major mode binding
164 may be shadowed from time to time by minor modes.
167 Do not bind @kbd{C-h} following any prefix character (including
168 @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
169 as a help character for listing the subcommands of the prefix character.
172 Do not bind a key sequence ending in @key{ESC} except following
173 another @key{ESC}. (That is, it is OK to bind a sequence ending in
174 @kbd{@key{ESC} @key{ESC}}.)
176 The reason for this rule is that a non-prefix binding for @key{ESC} in
177 any context prevents recognition of escape sequences as function keys in
181 Anything which acts like a temporary mode or state which the user can
182 enter and leave should define @kbd{@key{ESC} @key{ESC}} or
183 @kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
185 For a state which accepts ordinary Emacs commands, or more generally any
186 kind of state in which @key{ESC} followed by a function key or arrow key
187 is potentially meaningful, then you must not define @kbd{@key{ESC}
188 @key{ESC}}, since that would preclude recognizing an escape sequence
189 after @key{ESC}. In these states, you should define @kbd{@key{ESC}
190 @key{ESC} @key{ESC}} as the way to escape. Otherwise, define
191 @kbd{@key{ESC} @key{ESC}} instead.
195 @cindex references, following
196 Special major modes used for read-only text should usually redefine
197 @kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
198 Modes such as Dired, Info, Compilation, and Occur redefine it in this
201 In addition, they should mark the text as a kind of ``link'' so that
202 @kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}.
205 When a package provides a modification of ordinary Emacs behavior, it is
206 good to include a command to enable and disable the feature, provide a
207 command named @code{@var{whatever}-mode} which turns the feature on or
208 off, and make it autoload (@pxref{Autoload}). Design the package so
209 that simply loading it has no visible effect---that should not enable
210 the feature.@footnote{Consider that the package may be loaded
211 arbitrarily by Custom for instance.} Users will request the feature by
212 invoking the command. It is a good idea to define this command
215 @cindex unloading packages
216 If loading the file adds functions to hooks, define a function
217 @code{@var{feature}-unload-hook}, where @var{feature} is the name of
218 the feature the package provides, and make it undo any such changes.
219 Using @code{unload-feature} to unload the file will run this function.
223 It is a bad idea to define aliases for the Emacs primitives. Use the
224 standard names instead.
227 If a package needs to define an alias or a new function for
228 compatibility with some other version of Emacs, name it with the package
229 prefix, not with the raw name with which it occurs in the other version.
230 Here is an example from Gnus, which provides many examples of such
231 compatibility issues.
234 (defalias 'gnus-point-at-bol
235 (if (fboundp 'point-at-bol)
237 'line-beginning-position))
241 Redefining (or advising) an Emacs primitive is discouraged. It may do
242 the right thing for a particular program, but there is no telling what
243 other programs might break as a result.
246 If a file does replace any of the functions or library programs of
247 standard Emacs, prominent comments at the beginning of the file should
248 say which functions are replaced, and how the behavior of the
249 replacements differs from that of the originals.
252 Avoid using macros that define functions and variables with names that
253 are constructed. It is best for maintenance when the name of the
254 function or variable being defined is given explicitly in the source
255 code, as the second element of the list---as it is when you use
256 @code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}.
259 Please keep the names of your Emacs Lisp source files to 13 characters
260 or less. This way, if the files are compiled, the compiled files' names
261 will be 14 characters or less, which is short enough to fit on all kinds
265 Don't use @code{next-line} or @code{previous-line} in programs; nearly
266 always, @code{forward-line} is more convenient as well as more
267 predictable and robust. @xref{Text Lines}.
270 Don't call functions that set the mark, unless setting the mark is one
271 of the intended features of your program. The mark is a user-level
272 feature, so it is incorrect to change the mark except to supply a value
273 for the user's benefit. @xref{The Mark}.
275 In particular, don't use any of these functions:
279 @code{beginning-of-buffer}, @code{end-of-buffer}
281 @code{replace-string}, @code{replace-regexp}
284 If you just want to move point, or replace a certain string, without any
285 of the other features intended for interactive users, you can replace
286 these functions with one or two lines of simple Lisp code.
289 Use lists rather than vectors, except when there is a particular reason
290 to use a vector. Lisp has more facilities for manipulating lists than
291 for vectors, and working with lists is usually more convenient.
293 Vectors are advantageous for tables that are substantial in size and are
294 accessed in random order (not searched front to back), provided there is
295 no need to insert or delete elements (only lists allow that).
298 The recommended way to print a message in the echo area is with
299 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
302 When you encounter an error condition, call the function @code{error}
303 (or @code{signal}). The function @code{error} does not return.
304 @xref{Signaling Errors}.
306 Do not use @code{message}, @code{throw}, @code{sleep-for},
307 or @code{beep} to report errors.
310 An error message should start with a capital letter but should not end
314 In @code{interactive}, if you use a Lisp expression to produce a list
315 of arguments, don't try to provide the ``correct'' default values for
316 region or position arguments. Instead, provide @code{nil} for those
317 arguments if they were not specified, and have the function body
318 compute the default value when the argument is @code{nil}. For
319 instance, write this:
324 (list (if @var{specified} @var{specified-pos})))
325 (unless pos (setq pos @var{default-pos}))
335 (list (if @var{specified} @var{specified-pos}
341 This is so that repetition of the command will recompute
342 these defaults based on the current circumstances.
344 You do not need to take such precautions when you use interactive
345 specs @samp{d}, @samp{m} and @samp{r}, because they make special
346 arrangements to recompute the argument values on repetition of the
350 Many commands that take a long time to execute display a message that
351 says something like @samp{Operating...} when they start, and change it to
352 @samp{Operating...done} when they finish. Please keep the style of
353 these messages uniform: @emph{no} space around the ellipsis, and
354 @emph{no} period after @samp{done}.
357 Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
358 command does: use a new local keymap that contains one command defined
359 to switch back to the old local keymap. Or do what the
360 @code{edit-options} command does: switch to another buffer and let the
361 user switch back at will. @xref{Recursive Editing}.
364 In some other systems there is a convention of choosing variable names
365 that begin and end with @samp{*}. We don't use that convention in Emacs
366 Lisp, so please don't use it in your programs. (Emacs uses such names
367 only for special-purpose buffers.) The users will find Emacs more
368 coherent if all libraries use the same conventions.
371 Try to avoid compiler warnings about undefined free variables, by adding
372 dummy @code{defvar} definitions for these variables, like this:
378 Such a definition has no effect except to tell the compiler
379 not to warn about uses of the variable @code{foo} in this file.
382 If you use many functions and variables from a certain file, you can
383 add a @code{require} for that package to avoid compilation warnings
384 for them. For instance,
392 If you bind a variable in one function, and use it or set it in
393 another function, the compiler warns about the latter function unless
394 the variable has a definition. But adding a definition would be
395 unclean if the variable has a short name, since Lisp packages should
396 not define short variable names. The right thing to do is to rename
397 this variable to start with the name prefix used for the other
398 functions and variables in your package.
401 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
402 default indentation parameters.
405 Don't make a habit of putting close-parentheses on lines by themselves;
406 Lisp programmers find this disconcerting. Once in a while, when there
407 is a sequence of many consecutive close-parentheses, it may make sense
408 to split the sequence in one or two significant places.
411 Please put a copyright notice on the file if you give copies to anyone.
412 Use a message like this one:
415 ;; Copyright (C) @var{year} @var{name}
417 ;; This program is free software; you can redistribute it and/or
418 ;; modify it under the terms of the GNU General Public License as
419 ;; published by the Free Software Foundation; either version 2 of
420 ;; the License, or (at your option) any later version.
422 ;; This program is distributed in the hope that it will be
423 ;; useful, but WITHOUT ANY WARRANTY; without even the implied
424 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
425 ;; PURPOSE. See the GNU General Public License for more details.
427 ;; You should have received a copy of the GNU General Public
428 ;; License along with this program; if not, write to the Free
429 ;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
433 If you have signed papers to assign the copyright to the Foundation,
434 then use @samp{Free Software Foundation, Inc.} as @var{name}.
435 Otherwise, use your name. See also @xref{Library Headers}.
438 @node Compilation Tips
439 @section Tips for Making Compiled Code Fast
440 @cindex execution speed
443 Here are ways of improving the execution speed of byte-compiled
449 @cindex timing programs
450 @cindex @file{elp.el}
451 Profile your program with the @file{elp} library. See the file
452 @file{elp.el} for instructions.
455 Use iteration rather than recursion whenever possible.
456 Function calls are slow in Emacs Lisp even when a compiled function
457 is calling another compiled function.
460 Using the primitive list-searching functions @code{memq}, @code{member},
461 @code{assq}, or @code{assoc} is even faster than explicit iteration. It
462 can be worth rearranging a data structure so that one of these primitive
463 search functions can be used.
466 Certain built-in functions are handled specially in byte-compiled code,
467 avoiding the need for an ordinary function call. It is a good idea to
468 use these functions rather than alternatives. To see whether a function
469 is handled specially by the compiler, examine its @code{byte-compile}
470 property. If the property is non-@code{nil}, then the function is
473 For example, the following input will show you that @code{aref} is
474 compiled specially (@pxref{Array Functions}):
478 (get 'aref 'byte-compile)
479 @result{} byte-compile-two-args
484 If calling a small function accounts for a substantial part of your
485 program's running time, make the function inline. This eliminates
486 the function call overhead. Since making a function inline reduces
487 the flexibility of changing the program, don't do it unless it gives
488 a noticeable speedup in something slow enough that users care about
489 the speed. @xref{Inline Functions}.
492 @node Documentation Tips
493 @section Tips for Documentation Strings
495 @findex checkdoc-minor-mode
496 Here are some tips and conventions for the writing of documentation
497 strings. You can check many of these conventions by running the command
498 @kbd{M-x checkdoc-minor-mode}.
502 Every command, function, or variable intended for users to know about
503 should have a documentation string.
506 An internal variable or subroutine of a Lisp program might as well have
507 a documentation string. In earlier Emacs versions, you could save space
508 by using a comment instead of a documentation string, but that is no
509 longer the case---documentation strings now take up very little space in
513 Format the documentation string so that it fits in an Emacs window on an
514 80-column screen. It is a good idea for most lines to be no wider than
515 60 characters. The first line should not be wider than 67 characters
516 or it will look bad in the output of @code{apropos}.
518 You can fill the text if that looks good. However, rather than blindly
519 filling the entire documentation string, you can often make it much more
520 readable by choosing certain line breaks with care. Use blank lines
521 between topics if the documentation string is long.
524 The first line of the documentation string should consist of one or two
525 complete sentences that stand on their own as a summary. @kbd{M-x
526 apropos} displays just the first line, and if that line's contents don't
527 stand on their own, the result looks bad. In particular, start the
528 first line with a capital letter and end with a period.
530 For a function, the first line should briefly answer the question,
531 ``What does this function do?'' For a variable, the first line should
532 briefly answer the question, ``What does this value mean?''
534 Don't limit the documentation string to one line; use as many lines as
535 you need to explain the details of how to use the function or
536 variable. Please use complete sentences for the rest of the text too.
539 The first line should mention all the important arguments of the
540 function, and should mention them in the order that they are written
541 in a function call. If the function has many arguments, then it is
542 not feasible to mention them all in the first line; in that case, the
543 first line should mention the first few arguments, including the most
547 For consistency, phrase the verb in the first sentence of a function's
548 documentation string as an imperative---for instance, use ``Return the
549 cons of A and B.'' in preference to ``Returns the cons of A and B@.''
550 Usually it looks good to do likewise for the rest of the first
551 paragraph. Subsequent paragraphs usually look better if each sentence
552 is indicative and has a proper subject.
555 Write documentation strings in the active voice, not the passive, and in
556 the present tense, not the future. For instance, use ``Return a list
557 containing A and B.'' instead of ``A list containing A and B will be
561 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
562 Instead of, ``Cause Emacs to display text in boldface,'' write just
563 ``Display text in boldface.''
566 When a command is meaningful only in a certain mode or situation,
567 do mention that in the documentation string. For example,
568 the documentation of @code{dired-find-file} is:
571 In Dired, visit the file or directory named on this line.
575 Do not start or end a documentation string with whitespace.
578 @strong{Do not} indent subsequent lines of a documentation string so
579 that the text is lined up in the source code with the text of the first
580 line. This looks nice in the source code, but looks bizarre when users
581 view the documentation. Remember that the indentation before the
582 starting double-quote is not part of the string!
585 When the user tries to use a disabled command, Emacs displays just the
586 first paragraph of its documentation string---everything through the
587 first blank line. If you wish, you can choose which information to
588 include before the first blank line so as to make this display useful.
591 A variable's documentation string should start with @samp{*} if the
592 variable is one that users would often want to set interactively. If
593 the value is a long list, or a function, or if the variable would be set
594 only in init files, then don't start the documentation string with
595 @samp{*}. @xref{Defining Variables}.
598 The documentation string for a variable that is a yes-or-no flag should
599 start with words such as ``Non-nil means@dots{}'', to make it clear that
600 all non-@code{nil} values are equivalent and indicate explicitly what
601 @code{nil} and non-@code{nil} mean.
604 The documentation string for a function that is a yes-or-no predicate
605 should start with words such as ``Return t if @dots{}'', to indicate
606 explicitly what constitutes ``truth''. The word ``return'' avoids
607 starting the sentence with lower-case ``t'', which is somewhat
611 When a function's documentation string mentions the value of an argument
612 of the function, use the argument name in capital letters as if it were
613 a name for that value. Thus, the documentation string of the function
614 @code{eval} refers to its second argument as @samp{FORM}, because the
615 actual argument name is @code{form}:
618 Evaluate FORM and return its value.
621 Also write metasyntactic variables in capital letters, such as when you
622 show the decomposition of a list or vector into subunits, some of which
623 may vary. @samp{KEY} and @samp{VALUE} in the following example
624 illustrate this practice:
627 The argument TABLE should be an alist whose elements
628 have the form (KEY . VALUE). Here, KEY is ...
632 Never change the case of a Lisp symbol when you mention it in a doc
633 string. If the symbol's name is @code{foo}, write ``foo'', not
634 ``Foo'' (which is a different symbol).
636 This might appear to contradict the policy of writing function
637 argument values, but there is no real contradiction; the argument
638 @emph{value} is not the same thing as the @emph{symbol} which the
639 function uses to hold the value.
641 If this puts a lower-case letter at the beginning of a sentence
642 and that annoys you, rewrite the sentence so that the symbol
643 is not at the start of it.
646 If a line in a documentation string begins with an open-parenthesis,
647 write a backslash before the open-parenthesis, like this:
650 The argument FOO can be either a number
651 \(a buffer position) or a string (a file name).
654 This prevents the open-parenthesis from being treated as the start of a
655 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
657 @anchor{Docstring hyperlinks}
660 When a documentation string refers to a Lisp symbol, write it as it
661 would be printed (which usually means in lower case), with single-quotes
662 around it. For example: @samp{`lambda'}. There are two exceptions:
663 write @code{t} and @code{nil} without single-quotes.
666 When a documentation string refers to a Lisp symbol, write it as it
667 would be printed (which usually means in lower case), with single-quotes
668 around it. For example: @samp{lambda}. There are two exceptions: write
669 t and nil without single-quotes. (In this manual, we use a different
670 convention, with single-quotes for all symbols.)
673 Help mode automatically creates a hyperlink when a documentation string
674 uses a symbol name inside single quotes, if the symbol has either a
675 function or a variable definition. You do not need to do anything
676 special to make use of this feature. However, when a symbol has both a
677 function definition and a variable definition, and you want to refer to
678 just one of them, you can specify which one by writing one of the words
679 @samp{variable}, @samp{option}, @samp{function}, or @samp{command},
680 immediately before the symbol name. (Case makes no difference in
681 recognizing these indicator words.) For example, if you write
684 This function sets the variable `buffer-file-name'.
688 then the hyperlink will refer only to the variable documentation of
689 @code{buffer-file-name}, and not to its function documentation.
691 If a symbol has a function definition and/or a variable definition, but
692 those are irrelevant to the use of the symbol that you are documenting,
693 you can write the word @samp{symbol} before the symbol name to prevent
694 making any hyperlink. For example,
697 If the argument KIND-OF-RESULT is the symbol `list',
698 this function returns a list of all the objects
699 that satisfy the criterion.
703 does not make a hyperlink to the documentation, irrelevant here, of the
704 function @code{list}.
706 Normally, no hyperlink is made for a variable without variable
707 documentation. You can force a hyperlink for such variables by
708 preceding them with one of the words @samp{variable} or
711 Hyperlinks for faces are only made if the face name is preceded or
712 followed by the word @samp{face}. In that case, only the face
713 documentation will be shown, even if the symbol is also defined as a
714 variable or as a function.
716 To make a hyperlink to Info documentation, write the name of the Info
717 node (or anchor) in single quotes, preceded by @samp{info node},
718 @samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info
719 file name defaults to @samp{emacs}. For example,
722 See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
726 Don't write key sequences directly in documentation strings. Instead,
727 use the @samp{\\[@dots{}]} construct to stand for them. For example,
728 instead of writing @samp{C-f}, write the construct
729 @samp{\\[forward-char]}. When Emacs displays the documentation string,
730 it substitutes whatever key is currently bound to @code{forward-char}.
731 (This is normally @samp{C-f}, but it may be some other character if the
732 user has moved key bindings.) @xref{Keys in Documentation}.
735 In documentation strings for a major mode, you will want to refer to the
736 key bindings of that mode's local map, rather than global ones.
737 Therefore, use the construct @samp{\\<@dots{}>} once in the
738 documentation string to specify which key map to use. Do this before
739 the first use of @samp{\\[@dots{}]}. The text inside the
740 @samp{\\<@dots{}>} should be the name of the variable containing the
741 local keymap for the major mode.
743 It is not practical to use @samp{\\[@dots{}]} very many times, because
744 display of the documentation string will become slow. So use this to
745 describe the most important commands in your major mode, and then use
746 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
750 @section Tips on Writing Comments
752 We recommend these conventions for where to put comments and how to
757 Comments that start with a single semicolon, @samp{;}, should all be
758 aligned to the same column on the right of the source code. Such
759 comments usually explain how the code on the same line does its job. In
760 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
761 command automatically inserts such a @samp{;} in the right place, or
762 aligns such a comment if it is already present.
764 This and following examples are taken from the Emacs sources.
768 (setq base-version-list ; there was a base
769 (assoc (substring fn 0 start-vn) ; version to which
770 file-version-assoc-list)) ; this looks like
776 Comments that start with two semicolons, @samp{;;}, should be aligned to
777 the same level of indentation as the code. Such comments usually
778 describe the purpose of the following lines or the state of the program
779 at that point. For example:
783 (prog1 (setq auto-fill-function
787 (force-mode-line-update)))
791 We also normally use two semicolons for comments outside functions.
795 ;; This Lisp code is run in Emacs
796 ;; when it is to operate as a server
797 ;; for other processes.
801 Every function that has no documentation string (presumably one that is
802 used only internally within the package it belongs to), should instead
803 have a two-semicolon comment right before the function, explaining what
804 the function does and how to call it properly. Explain precisely what
805 each argument means and how the function interprets its possible values.
808 Comments that start with three semicolons, @samp{;;;}, should start at
809 the left margin. These are used, occasionally, for comments within
810 functions that should start at the margin. We also use them sometimes
811 for comments that are between functions---whether to use two or three
812 semicolons depends on whether the comment should be considered a
813 ``heading'' by Outline minor mode. By default, comments starting with
814 at least three semicolons (followed by a single space and a
815 non-whitespace character) are considered headings, comments starting
816 with two or less are not.
818 Another use for triple-semicolon comments is for commenting out lines
819 within a function. We use three semicolons for this precisely so that
820 they remain at the left margin. By default, Outline minor mode does
821 not consider a comment to be a heading (even if it starts with at
822 least three semicolons) if the semicolons are followed by at least two
823 spaces. Thus, if you add an introductory comment to the commented out
824 code, make sure to indent it by at least two spaces after the three
829 ;;; This is no longer necessary.
830 ;;; (force-mode-line-update)
831 (message "Finished with %s" a))
834 When commenting out entire functions, use two semicolons.
837 Comments that start with four semicolons, @samp{;;;;}, should be aligned
838 to the left margin and are used for headings of major sections of a
839 program. For example:
847 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
848 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
849 automatically indent comments according to these conventions,
850 depending on the number of semicolons. @xref{Comments,,
851 Manipulating Comments, emacs, The GNU Emacs Manual}.
853 @node Library Headers
854 @section Conventional Headers for Emacs Libraries
855 @cindex header comments
856 @cindex library header comments
858 Emacs has conventions for using special comments in Lisp libraries
859 to divide them into sections and give information such as who wrote
860 them. This section explains these conventions.
862 We'll start with an example, a package that is included in the Emacs
865 Parts of this example reflect its status as part of Emacs; for
866 example, the copyright notice lists the Free Software Foundation as the
867 copyright holder, and the copying permission says the file is part of
868 Emacs. When you write a package and post it, the copyright holder would
869 be you (unless your employer claims to own it instead), and you should
870 get the suggested copying permission from the end of the GNU General
871 Public License itself. Don't say your file is part of Emacs
872 if we haven't installed it in Emacs yet!
874 With that warning out of the way, on to the example:
878 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
880 ;; Copyright (C) 1992 Free Software Foundation, Inc.
883 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
884 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
885 ;; Created: 14 Jul 1992
890 ;; This file is part of GNU Emacs.
892 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
893 ;; Boston, MA 02111-1307, USA.
897 The very first line should have this format:
900 ;;; @var{filename} --- @var{description}
904 The description should be complete in one line. If the file
905 needs a @samp{-*-} specification, put it after @var{description}.
907 After the copyright notice come several @dfn{header comment} lines,
908 each beginning with @samp{;; @var{header-name}:}. Here is a table of
909 the conventional possibilities for @var{header-name}:
913 This line states the name and net address of at least the principal
914 author of the library.
916 If there are multiple authors, you can list them on continuation lines
917 led by @code{;;} and a tab character, like this:
921 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
922 ;; Dave Sill <de5@@ornl.gov>
923 ;; Dave Brennan <brennan@@hal.com>
924 ;; Eric Raymond <esr@@snark.thyrsus.com>
929 This line should contain a single name/address as in the Author line, or
930 an address only, or the string @samp{FSF}. If there is no maintainer
931 line, the person(s) in the Author field are presumed to be the
932 maintainers. The example above is mildly bogus because the maintainer
935 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
936 possible a Lisp function to ``send mail to the maintainer'' without
937 having to mine the name out by hand.
939 Be sure to surround the network address with @samp{<@dots{}>} if
940 you include the person's full name as well as the network address.
943 This optional line gives the original creation date of the
944 file. For historical interest only.
947 If you wish to record version numbers for the individual Lisp program, put
951 In this header line, place the name of the person who adapted the
952 library for installation (to make it fit the style conventions, for
956 This line lists keywords for the @code{finder-by-keyword} help command.
957 Please use that command to see a list of the meaningful keywords.
959 This field is important; it's how people will find your package when
960 they're looking for things by topic area. To separate the keywords, you
961 can use spaces, commas, or both.
964 Just about every Lisp library ought to have the @samp{Author} and
965 @samp{Keywords} header comment lines. Use the others if they are
966 appropriate. You can also put in header lines with other header
967 names---they have no standard meanings, so they can't do any harm.
969 We use additional stylized comments to subdivide the contents of the
970 library file. These should be separated by blank lines from anything
971 else. Here is a table of them:
974 @item ;;; Commentary:
975 This begins introductory comments that explain how the library works.
976 It should come right after the copying permissions, terminated by a
977 @samp{Change Log}, @samp{History} or @samp{Code} comment line. This
978 text is used by the Finder package, so it should make sense in that
981 @item ;;; Documentation:
982 This was used in some files in place of @samp{;;; Commentary:},
983 but it is deprecated.
985 @item ;;; Change Log:
986 This begins change log information stored in the library file (if you
987 store the change history there). For Lisp files distributed with Emacs,
988 the change history is kept in the file @file{ChangeLog} and not in the
989 source file at all; these files generally do not have a @samp{;;; Change
990 Log:} line. @samp{History} is an alternative to @samp{Change Log}.
993 This begins the actual code of the program.
995 @item ;;; @var{filename} ends here
996 This is the @dfn{footer line}; it appears at the very end of the file.
997 Its purpose is to enable people to detect truncated versions of the file
998 from the lack of a footer line.
1002 arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e