comparison lispref/tips.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, Calendar, Top
@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
@cindex coding standards

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 Emacs 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

@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

Instead, define sequences consisting of @kbd{C-c} followed by a control
character, a digit, or certain punctuation characters.  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.

@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
Do 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
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
Try to avoid compiler warnings about undefined free variables, by adding
@code{defvar} definitions for these variables.

@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 a message like this one:

@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.

@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 the construct

  ;; update mode line
  (force-mode-line-update)))
@end group
@end smallexample

Every function that has no documentation string (because it is use 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.

@end smallexample
@end table

@noindent
The indentation commands of the Lisp modes in Emacs, 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, emacs, The GNU Emacs Manual}.

@node Library Headers

;; Version: 1.2
@group
;; Keywords: docs

;; This file is part of GNU Emacs.
@var{copying permissions}@dots{}
@end group
@end smallexample

  The very first line should have this format:

21682:90da2489c498

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, System Interface, Top
@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
@cindex coding standards

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 Emacs Lisp---even to
@code{copy-list}.  Believe it or not, there is more than one plausible
way to define @code{copy-list}.  Play it safe; append your name prefix
to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
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

@example
(eval-when-compile (require '@var{bar}))
@end example

@noindent
(And the library @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

Instead, define sequences consisting of @kbd{C-c} followed by a control
character, a digit, or certain punctuation characters.  These sequences
are reserved for major modes.

Changing all the Emacs major modes to 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.

@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
Do 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
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 special-purpose buffers.)  The users will find Emacs more
coherent if all libraries use the same conventions.

@item
Try to avoid compiler warnings about undefined free variables, by adding
@code{defvar} definitions for these variables.

@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 the sequence in one or two significant places.

@item
Please put a copyright notice on the file if you give copies to anyone.
Use a message like this one:

@end itemize

@node Documentation Tips
@section Tips for Documentation Strings

@tindex checkdoc-minor-mode
@findex checkdoc-minor-mode
  Here are some tips and conventions for the writing of documentation
strings.  You can check many of these conventions by running the command
@kbd{M-x checkdoc-minor-mode}.

@itemize @bullet
@item
Every command, function, or variable intended for users to know about
should have a documentation string.

@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 use a different
convention, with single-quotes for all symbols.)
@end ifinfo

For example:

@example
The value of `swim-speed' specifies how fast to swim.
Possible values are t for high speed, nil for low speed,
and `medium' for medium speed.
@end example

@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 the construct

  ;; update mode line
  (force-mode-line-update)))
@end group
@end smallexample

Every function that has no documentation string (presumably one that 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.

@end smallexample
@end table

@noindent
The indentation commands of the Lisp modes in Emacs, 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, emacs, The GNU Emacs Manual}.

@node Library Headers

;; Version: 1.2
@group
;; Keywords: docs

;; This file is part of GNU Emacs.
@dots{}
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
@end group
@end smallexample

  The very first line should have this format: