Lisp programs. The names of all global symbols in your program, that
is the names of variables, constants, and functions, should begin with
that chosen prefix. Separate the prefix from the rest of the name
-with a hyphen, @samp{-}. Use two hyphens if the symbol is not meant
-to be used by other packages. This practice helps avoid name
-conflicts, since all global variables in Emacs Lisp share the same
-name space, and all functions share another name space@footnote{The
-benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.}.
+with a hyphen, @samp{-}. This practice helps avoid name conflicts,
+since all global variables in Emacs Lisp share the same name space,
+and all functions share another name space@footnote{The benefits of a
+Common Lisp-style package system are considered not to outweigh the
+costs.}. Use two hyphens to separate prefix and name if the symbol is
+not meant to be used by other packages.
Occasionally, for a command name intended for users to use, it is more
convenient if some words come before the package's name prefix. And
coherent if all libraries use the same conventions.
@item
-If your program contains non-ASCII characters in string or character
-constants, you should make sure Emacs always decodes these characters
-the same way, regardless of the user's settings. The easiest way to
-do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding
-System Basics}), and specify that coding in the @samp{-*-} line or the
+The default file coding system for Emacs Lisp source files is UTF-8
+(@pxref{Text Representations}). In the rare event that your program
+contains characters which are @emph{not} in UTF-8, you should specify
+an appropriate coding system in the source file's @samp{-*-} line or
local variables list. @xref{File Variables, , Local Variables in
Files, emacs, The GNU Emacs Manual}.
-@example
-;; XXX.el -*- coding: utf-8-emacs; -*-
-@end example
-
@item
Indent the file using the default indentation parameters.
@smallexample
@group
-(setq base-version-list ; there was a base
+(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
+ ; a subversion.
@end group
@end smallexample
@item ;;;
Comments that start with three semicolons, @samp{;;;}, should start at
-the left margin. These are used, occasionally, for comments within
-functions that should start at the margin. We also use them sometimes
-for comments that are between functions---whether to use two or three
-semicolons depends on whether the comment should be considered a
+the left margin. We use them
+for comments which should be considered a
``heading'' by Outline minor mode. By default, comments starting with
at least three semicolons (followed by a single space and a
non-whitespace character) are considered headings, comments starting
-with two or fewer are not.
-
-Another use for triple-semicolon comments is for commenting out lines
-within a function. We use three semicolons for this precisely so that
-they remain at the left margin. By default, Outline minor mode does
-not consider a comment to be a heading (even if it starts with at
-least three semicolons) if the semicolons are followed by at least two
-spaces. Thus, if you add an introductory comment to the commented out
-code, make sure to indent it by at least two spaces after the three
-semicolons.
-
-@smallexample
-(defun foo (a)
-;;; This is no longer necessary.
-;;; (force-mode-line-update)
- (message "Finished with %s" a))
-@end smallexample
+with two or fewer are not. Historically, triple-semicolon comments have
+also been used for commenting out lines within a function, but this use
+is discouraged.
When commenting out entire functions, use two semicolons.
HCoop / bpt / emacs.git / blobdiff