comparison lispref/tips.texi @ 17280:96762d1abb7c

(Coding Conventions): Node renamed from Style Tips. Xref the Major Mode Conventions and Minor Mode Conventions nodes. Other smaller changes in it.

17279:d2c67029b824

@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 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 Standards
@cindex tips
@cindex standards of coding style
@cindex coding standards

  This chapter describes no additional features of Emacs 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

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,

@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 Emacs, prominent comments at the beginning of the file should
say which functions are replaced, and how the behavior of the

17280:96762d1abb7c

@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 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

  This chapter describes no additional features of Emacs Lisp.  Instead
it gives advice on making effective use of the features described in the
previous chapters, and describes conventions Emacs Lisp programmers
should follow.

@menu
* Coding Conventions::        Conventions for 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 Coding Conventions
@section Emacs Lisp Coding Conventions

  Here are conventions that you should follow when writing Emacs 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

Using @code{eval-when-compile} avoids loading @var{bar} when
the compiled version of @var{foo} is @emph{used}.

@item
When defining a major mode, please follow the major mode
conventions.  @xref{Major Mode Conventions}.

@item
When defining a minor mode, please follow the minor mode
conventions.  @xref{Minor Mode Conventions}.

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

@item
It is a bad idea to define aliases for the Emacs primitives.  Use the
standard names instead.

@item
Redefining (or advising) an Emacs primitive is discouraged.  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 Emacs, prominent comments at the beginning of the file should
say which functions are replaced, and how the behavior of the