--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/tips.info
+@node Tips, Building XEmacs and Object Allocation, MULE, Top
+@appendix Tips and Standards
+@cindex tips
+@cindex standards of coding style
+@cindex coding standards
+
+ This chapter describes no additional features of XEmacs Lisp.
+Instead it gives advice on making effective use of the features described
+in the previous chapters.
+
+@menu
+* Style Tips:: Writing clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
+@end menu
+
+@node Style Tips
+@section Writing Clean Lisp Programs
+
+ Here are some tips for avoiding common errors in writing Lisp code
+intended for widespread use:
+
+@itemize @bullet
+@item
+Since all global variables share the same name space, and all functions
+share another name space, you should choose a short word to distinguish
+your program from other Lisp programs. Then take care to begin the
+names of all global variables, constants, and functions with the chosen
+prefix. This helps avoid name conflicts.
+
+This recommendation applies even to names for traditional Lisp
+primitives that are not primitives in XEmacs Lisp---even to @code{cadr}.
+Believe it or not, there is more than one plausible way to define
+@code{cadr}. Play it safe; append your name prefix to produce a name
+like @code{foo-cadr} or @code{mylib-cadr} instead.
+
+If you write a function that you think ought to be added to Emacs under
+a certain name, such as @code{twiddle-files}, don't call it by that name
+in your program. Call it @code{mylib-twiddle-files} in your program,
+and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
+it to Emacs. If and when we do, we can change the name easily enough.
+
+If one prefix is insufficient, your package may use two or three
+alternative common prefixes, so long as they make sense.
+
+Separate the prefix from the rest of the symbol name with a hyphen,
+@samp{-}. This will be consistent with XEmacs itself and with most Emacs
+Lisp programs.
+
+@item
+It is often useful to put a call to @code{provide} in each separate
+library program, at least if there is more than one entry point to the
+program.
+
+@item
+If a file requires certain other library programs to be loaded
+beforehand, then the comments at the beginning of the file should say
+so. Also, use @code{require} to make sure they are loaded.
+
+@item
+If one file @var{foo} uses a macro defined in another file @var{bar},
+@var{foo} should contain this expression before the first use of the
+macro:
+
+@example
+(eval-when-compile (require '@var{bar}))
+@end example
+
+@noindent
+(And @var{bar} should contain @code{(provide '@var{bar})}, to make the
+@code{require} work.) This will cause @var{bar} to be loaded when you
+byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without
+the necessary macro loaded, and that would produce compiled code that
+won't work right. @xref{Compiling Macros}.
+
+Using @code{eval-when-compile} avoids loading @var{bar} when
+the compiled version of @var{foo} is @emph{used}.
+
+@item
+If you define a major mode, make sure to run a hook variable using
+@code{run-hooks}, just as the existing major modes do. @xref{Hooks}.
+
+@item
+If the purpose of a function is to tell you whether a certain condition
+is true or false, give the function a name that ends in @samp{p}. If
+the name is one word, add just @samp{p}; if the name is multiple words,
+add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
+
+@item
+If a user option variable records a true-or-false condition, give it a
+name that ends in @samp{-flag}.
+
+@item
+Please do not define @kbd{C-c @var{letter}} as a key in your major
+modes. These sequences are reserved for users; they are the
+@strong{only} sequences reserved for users, so we cannot do without
+them.
+
+Instead, define sequences consisting of @kbd{C-c} followed by a
+non-letter. These sequences are reserved for major modes.
+
+Changing all the major modes in Emacs 18 so they would follow this
+convention was a lot of work. Abandoning this convention would make
+that work go to waste, and inconvenience users.
+
+@item
+Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
+@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
+
+@item
+Sequences consisting of @kbd{C-c} followed by any other punctuation
+character are allocated for minor modes. Using them in a major mode is
+not absolutely prohibited, but if you do that, the major mode binding
+may be shadowed from time to time by minor modes.
+
+@item
+You should not bind @kbd{C-h} following any prefix character (including
+@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
+as a help character for listing the subcommands of the prefix character.
+
+@item
+You should not bind a key sequence ending in @key{ESC} except following
+another @key{ESC}. (That is, it is ok to bind a sequence ending in
+@kbd{@key{ESC} @key{ESC}}.)
+
+The reason for this rule is that a non-prefix binding for @key{ESC} in
+any context prevents recognition of escape sequences as function keys in
+that context.
+
+@item
+Applications should not bind mouse events based on button 1 with the
+shift key held down. These events include @kbd{S-mouse-1},
+@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
+users.
+
+@item
+Modes should redefine @kbd{mouse-2} as a command to follow some sort of
+reference in the text of a buffer, if users usually would not want to
+alter the text in that buffer by hand. Modes such as Dired, Info,
+Compilation, and Occur redefine it in this way.
+
+@item
+When a package provides a modification of ordinary Emacs behavior, it is
+good to include a command to enable and disable the feature, Provide a
+command named @code{@var{whatever}-mode} which turns the feature on or
+off, and make it autoload (@pxref{Autoload}). Design the package so
+that simply loading it has no visible effect---that should not enable
+the feature. Users will request the feature by invoking the command.
+
+@item
+It is a bad idea to define aliases for the Emacs primitives. Use the
+standard names instead.
+
+@item
+Redefining an Emacs primitive is an even worse idea.
+It may do the right thing for a particular program, but
+there is no telling what other programs might break as a result.
+
+@item
+If a file does replace any of the functions or library programs of
+standard XEmacs, prominent comments at the beginning of the file should
+say which functions are replaced, and how the behavior of the
+replacements differs from that of the originals.
+
+@item
+Please keep the names of your XEmacs Lisp source files to 13 characters
+or less. This way, if the files are compiled, the compiled files' names
+will be 14 characters or less, which is short enough to fit on all kinds
+of Unix systems.
+
+@item
+Don't use @code{next-line} or @code{previous-line} in programs; nearly
+always, @code{forward-line} is more convenient as well as more
+predictable and robust. @xref{Text Lines}.
+
+@item
+Don't call functions that set the mark, unless setting the mark is one
+of the intended features of your program. The mark is a user-level
+feature, so it is incorrect to change the mark except to supply a value
+for the user's benefit. @xref{The Mark}.
+
+In particular, don't use these functions:
+
+@itemize @bullet
+@item
+@code{beginning-of-buffer}, @code{end-of-buffer}
+@item
+@code{replace-string}, @code{replace-regexp}
+@end itemize
+
+If you just want to move point, or replace a certain string, without any
+of the other features intended for interactive users, you can replace
+these functions with one or two lines of simple Lisp code.
+
+@item
+Use lists rather than vectors, except when there is a particular reason
+to use a vector. Lisp has more facilities for manipulating lists than
+for vectors, and working with lists is usually more convenient.
+
+Vectors are advantageous for tables that are substantial in size and are
+accessed in random order (not searched front to back), provided there is
+no need to insert or delete elements (only lists allow that).
+
+@item
+The recommended way to print a message in the echo area is with
+the @code{message} function, not @code{princ}. @xref{The Echo Area}.
+
+@item
+When you encounter an error condition, call the function @code{error}
+(or @code{signal}). The function @code{error} does not return.
+@xref{Signaling Errors}.
+
+Do not use @code{message}, @code{throw}, @code{sleep-for},
+or @code{beep} to report errors.
+
+@item
+An error message should start with a capital letter but should not end
+with a period.
+
+@item
+Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
+command does: use a new local keymap that contains one command defined
+to switch back to the old local keymap. Or do what the
+@code{edit-options} command does: switch to another buffer and let the
+user switch back at will. @xref{Recursive Editing}.
+
+@item
+In some other systems there is a convention of choosing variable names
+that begin and end with @samp{*}. We don't use that convention in Emacs
+Lisp, so please don't use it in your programs. (Emacs uses such names
+only for program-generated buffers.) The users will find Emacs more
+coherent if all libraries use the same conventions.
+
+@item
+Use names starting with a space for temporary buffers (@pxref{Buffer
+Names}), or at least call @code{buffer-disable-undo} on them. Otherwise
+they may stay referenced by internal undo variable(s) after getting
+killed. If this happens before dumping (@pxref{Building XEmacs}), this
+may cause fatal error when portable dumper is used.
+
+@item
+Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
+default indentation parameters.
+
+@item
+Don't make a habit of putting close-parentheses on lines by themselves;
+Lisp programmers find this disconcerting. Once in a while, when there
+is a sequence of many consecutive close-parentheses, it may make sense
+to split them in one or two significant places.
+
+@item
+Please put a copyright notice on the file if you give copies to anyone.
+Use the same lines that appear at the top of the Lisp files in XEmacs
+itself. If you have not signed papers to assign the copyright to the
+Foundation, then place your name in the copyright notice in place of the
+Foundation's name.
+@end itemize
+
+@node Compilation Tips
+@section Tips for Making Compiled Code Fast
+@cindex execution speed
+@cindex speedups
+
+ Here are ways of improving the execution speed of byte-compiled
+Lisp programs.
+
+@itemize @bullet
+@item
+@cindex profiling
+@cindex timing programs
+@cindex @file{profile.el}
+Use the @file{profile} library to profile your program. See the file
+@file{profile.el} for instructions.
+
+@item
+Use iteration rather than recursion whenever possible.
+Function calls are slow in XEmacs Lisp even when a compiled function
+is calling another compiled function.
+
+@item
+Using the primitive list-searching functions @code{memq}, @code{member},
+@code{assq}, or @code{assoc} is even faster than explicit iteration. It
+may be worth rearranging a data structure so that one of these primitive
+search functions can be used.
+
+@item
+Certain built-in functions are handled specially in byte-compiled code,
+avoiding the need for an ordinary function call. It is a good idea to
+use these functions rather than alternatives. To see whether a function
+is handled specially by the compiler, examine its @code{byte-compile}
+property. If the property is non-@code{nil}, then the function is
+handled specially.
+
+For example, the following input will show you that @code{aref} is
+compiled specially (@pxref{Array Functions}) while @code{elt} is not
+(@pxref{Sequence Functions}):
+
+@example
+@group
+(get 'aref 'byte-compile)
+ @result{} byte-compile-two-args
+@end group
+
+@group
+(get 'elt 'byte-compile)
+ @result{} nil
+@end group
+@end example
+
+@item
+If calling a small function accounts for a substantial part of your
+program's running time, make the function inline. This eliminates
+the function call overhead. Since making a function inline reduces
+the flexibility of changing the program, don't do it unless it gives
+a noticeable speedup in something slow enough that users care about
+the speed. @xref{Inline Functions}.
+@end itemize
+
+@node Documentation Tips
+@section Tips for Documentation Strings
+
+ Here are some tips for the writing of documentation strings.
+
+@itemize @bullet
+@item
+Every command, function, or variable intended for users to know about
+should have a documentation string.
+
+@item
+An internal variable or subroutine of a Lisp program might as well have
+a documentation string. In earlier Emacs versions, you could save space
+by using a comment instead of a documentation string, but that is no
+longer the case.
+
+@item
+The first line of the documentation string should consist of one or two
+complete sentences that stand on their own as a summary. @kbd{M-x
+apropos} displays just the first line, and if it doesn't stand on its
+own, the result looks bad. In particular, start the first line with a
+capital letter and end with a period.
+
+The documentation string can have additional lines that expand on the
+details of how to use the function or variable. The additional lines
+should be made up of complete sentences also, but they may be filled if
+that looks good.
+
+@item
+For consistency, phrase the verb in the first sentence of a
+documentation string as an infinitive with ``to'' omitted. For
+instance, use ``Return the cons of A and B.'' in preference to ``Returns
+the cons of A and B@.'' Usually it looks good to do likewise for the
+rest of the first paragraph. Subsequent paragraphs usually look better
+if they have proper subjects.
+
+@item
+Write documentation strings in the active voice, not the passive, and in
+the present tense, not the future. For instance, use ``Return a list
+containing A and B.'' instead of ``A list containing A and B will be
+returned.''
+
+@item
+Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+Instead of, ``Cause Emacs to display text in boldface,'' write just
+``Display text in boldface.''
+
+@item
+Do not start or end a documentation string with whitespace.
+
+@item
+Format the documentation string so that it fits in an Emacs window on an
+80-column screen. It is a good idea for most lines to be no wider than
+60 characters. The first line can be wider if necessary to fit the
+information that ought to be there.
+
+However, rather than simply filling the entire documentation string, you
+can make it much more readable by choosing line breaks with care.
+Use blank lines between topics if the documentation string is long.
+
+@item
+@strong{Do not} indent subsequent lines of a documentation string so
+that the text is lined up in the source code with the text of the first
+line. This looks nice in the source code, but looks bizarre when users
+view the documentation. Remember that the indentation before the
+starting double-quote is not part of the string!
+
+@item
+A variable's documentation string should start with @samp{*} if the
+variable is one that users would often want to set interactively. If
+the value is a long list, or a function, or if the variable would be set
+only in init files, then don't start the documentation string with
+@samp{*}. @xref{Defining Variables}.
+
+@item
+The documentation string for a variable that is a yes-or-no flag should
+start with words such as ``Non-nil means@dots{}'', to make it clear that
+all non-@code{nil} values are equivalent and indicate explicitly what
+@code{nil} and non-@code{nil} mean.
+
+@item
+When a function's documentation string mentions the value of an argument
+of the function, use the argument name in capital letters as if it were
+a name for that value. Thus, the documentation string of the function
+@code{/} refers to its second argument as @samp{DIVISOR}, because the
+actual argument name is @code{divisor}.
+
+Also use all caps for meta-syntactic variables, such as when you show
+the decomposition of a list or vector into subunits, some of which may
+vary.
+
+@item
+@iftex
+When a documentation string refers to a Lisp symbol, write it as it
+would be printed (which usually means in lower case), with single-quotes
+around it. For example: @samp{`lambda'}. There are two exceptions:
+write @code{t} and @code{nil} without single-quotes.
+@end iftex
+@ifinfo
+When a documentation string refers to a Lisp symbol, write it as it
+would be printed (which usually means in lower case), with single-quotes
+around it. For example: @samp{lambda}. There are two exceptions: write
+t and nil without single-quotes. (In this manual, we normally do use
+single-quotes for those symbols.)
+@end ifinfo
+
+@item
+Don't write key sequences directly in documentation strings. Instead,
+use the @samp{\\[@dots{}]} construct to stand for them. For example,
+instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When
+Emacs displays the documentation string, it substitutes whatever key is
+currently bound to @code{forward-char}. (This is normally @samp{C-f},
+but it may be some other character if the user has moved key bindings.)
+@xref{Keys in Documentation}.
+
+@item
+In documentation strings for a major mode, you will want to refer to the
+key bindings of that mode's local map, rather than global ones.
+Therefore, use the construct @samp{\\<@dots{}>} once in the
+documentation string to specify which key map to use. Do this before
+the first use of @samp{\\[@dots{}]}. The text inside the
+@samp{\\<@dots{}>} should be the name of the variable containing the
+local keymap for the major mode.
+
+It is not practical to use @samp{\\[@dots{}]} very many times, because
+display of the documentation string will become slow. So use this to
+describe the most important commands in your major mode, and then use
+@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
+@end itemize
+
+@node Comment Tips
+@section Tips on Writing Comments
+
+ We recommend these conventions for where to put comments and how to
+indent them:
+
+@table @samp
+@item ;
+Comments that start with a single semicolon, @samp{;}, should all be
+aligned to the same column on the right of the source code. Such
+comments usually explain how the code on the same line does its job. In
+Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
+command automatically inserts such a @samp{;} in the right place, or
+aligns such a comment if it is already present.
+
+This and following examples are taken from the Emacs sources.
+
+@smallexample
+@group
+(setq base-version-list ; there was a base
+ (assoc (substring fn 0 start-vn) ; version to which
+ file-version-assoc-list)) ; this looks like
+ ; a subversion
+@end group
+@end smallexample
+
+@item ;;
+Comments that start with two semicolons, @samp{;;}, should be aligned to
+the same level of indentation as the code. Such comments usually
+describe the purpose of the following lines or the state of the program
+at that point. For example:
+
+@smallexample
+@group
+(prog1 (setq auto-fill-function
+ @dots{}
+ @dots{}
+ ;; update modeline
+ (redraw-modeline)))
+@end group
+@end smallexample
+
+Every function that has no documentation string (because it is used only
+internally within the package it belongs to), should have instead a
+two-semicolon comment right before the function, explaining what the
+function does and how to call it properly. Explain precisely what each
+argument means and how the function interprets its possible values.
+
+@item ;;;
+Comments that start with three semicolons, @samp{;;;}, should start at
+the left margin. Such comments are used outside function definitions to
+make general statements explaining the design principles of the program.
+For example:
+
+@smallexample
+@group
+;;; This Lisp code is run in XEmacs
+;;; when it is to operate as a server
+;;; for other processes.
+@end group
+@end smallexample
+
+Another use for triple-semicolon comments is for commenting out lines
+within a function. We use triple-semicolons for this precisely so that
+they remain at the left margin.
+
+@smallexample
+(defun foo (a)
+;;; This is no longer necessary.
+;;; (force-mode-line-update)
+ (message "Finished with %s" a))
+@end smallexample
+
+@item ;;;;
+Comments that start with four semicolons, @samp{;;;;}, should be aligned
+to the left margin and are used for headings of major sections of a
+program. For example:
+
+@smallexample
+;;;; The kill ring
+@end smallexample
+@end table
+
+@noindent
+The indentation commands of the Lisp modes in XEmacs, such as @kbd{M-;}
+(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
+automatically indent comments according to these conventions,
+depending on the number of semicolons. @xref{Comments,,
+Manipulating Comments, xemacs, The XEmacs User's Manual}.
+
+@node Library Headers
+@section Conventional Headers for XEmacs Libraries
+@cindex header comments
+@cindex library header comments
+
+ XEmacs has conventions for using special comments in Lisp libraries
+to divide them into sections and give information such as who wrote
+them. This section explains these conventions. First, an example:
+
+@smallexample
+@group
+;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+
+;; Copyright (C) 1992 Free Software Foundation, Inc.
+@end group
+
+;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
+;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
+;; Created: 14 Jul 1992
+;; Version: 1.2
+@group
+;; Keywords: docs
+
+;; This file is part of XEmacs.
+@var{copying permissions}@dots{}
+@end group
+@end smallexample
+
+ The very first line should have this format:
+
+@example
+;;; @var{filename} --- @var{description}
+@end example
+
+@noindent
+The description should be complete in one line.
+
+ After the copyright notice come several @dfn{header comment} lines,
+each beginning with @samp{;; @var{header-name}:}. Here is a table of
+the conventional possibilities for @var{header-name}:
+
+@table @samp
+@item Author
+This line states the name and net address of at least the principal
+author of the library.
+
+If there are multiple authors, you can list them on continuation lines
+led by @code{;;} and a tab character, like this:
+
+@smallexample
+@group
+;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
+;; Dave Sill <de5@@ornl.gov>
+;; Dave Brennan <brennan@@hal.com>
+;; Eric Raymond <esr@@snark.thyrsus.com>
+@end group
+@end smallexample
+
+@item Maintainer
+This line should contain a single name/address as in the Author line, or
+an address only, or the string @samp{FSF}. If there is no maintainer
+line, the person(s) in the Author field are presumed to be the
+maintainers. The example above is mildly bogus because the maintainer
+line is redundant.
+
+The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
+possible a Lisp function to ``send mail to the maintainer'' without
+having to mine the name out by hand.
+
+Be sure to surround the network address with @samp{<@dots{}>} if
+you include the person's full name as well as the network address.
+
+@item Created
+This optional line gives the original creation date of the
+file. For historical interest only.
+
+@item Version
+If you wish to record version numbers for the individual Lisp program, put
+them in this line.
+
+@item Adapted-By
+In this header line, place the name of the person who adapted the
+library for installation (to make it fit the style conventions, for
+example).
+
+@item Keywords
+This line lists keywords for the @code{finder-by-keyword} help command.
+This field is important; it's how people will find your package when
+they're looking for things by topic area. To separate the keywords, you
+can use spaces, commas, or both.
+@end table
+
+ Just about every Lisp library ought to have the @samp{Author} and
+@samp{Keywords} header comment lines. Use the others if they are
+appropriate. You can also put in header lines with other header
+names---they have no standard meanings, so they can't do any harm.
+
+ We use additional stylized comments to subdivide the contents of the
+library file. Here is a table of them:
+
+@table @samp
+@item ;;; Commentary:
+This begins introductory comments that explain how the library works.
+It should come right after the copying permissions.
+
+@item ;;; Change log:
+This begins change log information stored in the library file (if you
+store the change history there). For most of the Lisp
+files distributed with XEmacs, the change history is kept in the file
+@file{ChangeLog} and not in the source file at all; these files do
+not have a @samp{;;; Change log:} line.
+
+@item ;;; Code:
+This begins the actual code of the program.
+
+@item ;;; @var{filename} ends here
+This is the @dfn{footer line}; it appears at the very end of the file.
+Its purpose is to enable people to detect truncated versions of the file
+from the lack of a footer line.
+@end table
projects / chise / xemacs-chise.git- / blobdiff