standard Emacs namespace. If your package loads @code{cl} at run time,
that could cause name clashes for users who don't use that package.
-However, there is no problem with using the @code{cl} package at compile
-time, with @code{(eval-when-compile (require 'cl))}.
+However, there is no problem with using the @code{cl} package at
+compile time, with @code{(eval-when-compile (require 'cl))}. That's
+sufficient for using the macros in the @code{cl} package, because the
+compiler expands them before generating the byte-code.
@item
When defining a major mode, please follow the major mode
Redefining (or advising) an Emacs primitive is a bad idea. It may do
the right thing for a particular program, but there is no telling what
other programs might break as a result. In any case, it is a problem
-for debugging, because the two advised function doesn't do what its
-source code says it does. If the programmer investigating the problem
-is unaware that there is advice on the function, the experience can be
+for debugging, because the advised function doesn't do what its source
+code says it does. If the programmer investigating the problem is
+unaware that there is advice on the function, the experience can be
very frustrating.
We hope to remove all the places in Emacs that advise primitives.
@item
Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
Loading}) in libraries and packages. This feature is meant for
-personal customizations; using it in a Lisp program is unclean because
-it modifies the behavior of another Lisp file in an invisible way.
-This is an obstacle for debugging, much like advising a function in
-the other package.
+personal customizations; using it in a Lisp program is unclean,
+because it modifies the behavior of another Lisp file in a way that's
+not visible in that file. This is an obstacle for debugging, much
+like advising a function in the other package.
@item
If a file does replace any of the functions or library programs of
replacements differs from that of the originals.
@item
-Avoid using macros that define functions and variables with names that
-are constructed. It is best for maintenance when the name of the
-function or variable being defined is given explicitly in the source
-code, as the second element of the list---as it is when you use
-@code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}.
+Constructs that define a function or variable should be macros,
+not functions, and their names should start with @samp{def}.
+
+@item
+Macros that define a functions or variables should take the name to be
+defined as the first argument. That will help various tools find the
+definition automatically. Avoid constructing the names in the macro
+itself, since that would confuse these tools.
@item
Please keep the names of your Emacs Lisp source files to 13 characters
@example
;; XXX.el -*- coding: iso-latin-2!; -*-
@end example
+@end itemize
@item
Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
-;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
-;; MA 02110-1301 USA
+;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301 USA
@end smallexample
If you have signed papers to assign the copyright to the Foundation,
@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
+start with words such as ``Non-nil means,'' to make it clear that
all non-@code{nil} values are equivalent and indicate explicitly what
@code{nil} and non-@code{nil} mean.
@item
The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if @dots{}'', to indicate
-explicitly what constitutes ``truth''. The word ``return'' avoids
-starting the sentence with lower-case ``t'', which is somewhat
+should start with words such as ``Return t if,'' to indicate
+explicitly what constitutes ``truth.'' The word ``return'' avoids
+starting the sentence with lower-case ``t,'' which could be somewhat
distracting.
@item
@item
Never change the case of a Lisp symbol when you mention it in a doc
-string. If the symbol's name is @code{foo}, write ``foo'', not
+string. If the symbol's name is @code{foo}, write ``foo,'' not
``Foo'' (which is a different symbol).
This might appear to contradict the policy of writing function