StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Update the Common Lisp Style Guide to 1.28.

Browse Source
This commit is contained in:
tunes@google.com 2014-03-18 00:14:41 +00:00
parent a5eb0c52f8
commit cf1841c032
1 changed files with 57 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
lispguide.xml
View File

@ -5,7 +5,7 @@
<p align="right"> <p align="right">
Revision 1.23 Revision 1.28
</p> </p>
@ -665,16 +665,35 @@ Robert Brown
<p> <p>
Indent your code the way a properly configured GNU Emacs does. Indent your code the way a properly configured GNU Emacs does.
</p> </p>
<p>
Maintain a consistent indentation style throughout a project.
</p>
<p> <p>
Indent carefully to make the code easier to understand. Indent carefully to make the code easier to understand.
</p> </p>
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
By default, GNU Emacs does an excellent job indenting Common Lisp code. Common Lisp indentation in Emacs is provided by the cl-indent library.
It can be taught how to indent new defining forms The latest version of cl-indent is packaged with
and special rules for domain specific languages. <a HREF="http://www.common-lisp.net/project/slime/">SLIME</a>
Each project may have some file to customize indentation; use it. (under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs
to load SLIME automatically using
<a HREF="http://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of
contrib libraries to be loaded in the call to slime-setup.
</p>
<p>
Ideally, use the default indentation settings provided by
slime-indentation. If necessary, customize indentation parameters to
maintain a consistent indentation style throughout an existing project.
Parameters can be customized using the :variables setting in
define-common-lisp-style. Indentation of specific forms can be
customized using the :indentation setting of define-common-lisp-style.
This is particularly useful when creating forms that behave like macros
or special operators that are indented differently than standard
function calls (e.g. defun, labels, or let). Add a
<a HREF="http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html">hook</a> to 'lisp-mode-hook that calls common-lisp-set-style to set
the appropriate style automatically.
</p> </p>
@ -728,27 +747,25 @@ Robert Brown
that is not covered by an <code>ASDF</code> <code>:around-compile</code> hook. that is not covered by an <code>ASDF</code> <code>:around-compile</code> hook.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
;;;; Author: brown (Robert Brown)
;;;; Variable length encoding for integers and floating point numbers. ;;;; Variable length encoding for integers and floating point numbers.
(in-package #:varint) (in-package #:varint)
(declaim #.*optimize-default*) (declaim #.*optimize-default*)
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
You should not include authorship information at the top of a file, You should not include authorship information at the top of a file:
that information is available from version control and better information is available from version control,
<code>OWNERS</code>. and such a mention will only cause confusion and grief.
Indeed, whoever was the main author at the time such a mention was included
might not be who eventually made the most significant contributions to the file,
and even less who is responsible for the file at the moment.
</p> </p>
<p> <p>
You should not include copyright information in individual source code files. You should not include copyright information in individual source code files.
An exception is made for files meant to be disseminated as standalone. An exception is made for files meant to be disseminated as standalone.
</p> </p>
<p>
Each project or library has a single file specifying its license.
Absence of a <tt>LICENSE</tt> or <tt>COPYING</tt> file
means the project is proprietary code.
</p>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -1109,12 +1126,19 @@ Robert Brown
</p> </p>
<p> <p>
The comments begin with <code>TODO</code> in all capital letters, The comments begin with <code>TODO</code> in all capital letters,
followed by your email address or other identifier in parentheses, followed by the
followed by a colon, a space, and
an explanation of what additional work is desirable or required. name, e-mail address, or other identifier
The user name included in the comment is that of the person
of a person who understands the deficiency. with the best context about the problem referenced by the <code>TODO</code>.
A TODO comment is not a commitment to fix the problem. The main purpose is to have a consistent <code>TODO</code> that
can be searched to find out how to get more details upon
request. A <code>TODO</code> is not a commitment that the
person referenced will fix the problem. Thus when you create
a <code>TODO</code>,
it is almost always your
name
that is given.
</p> </p>
<p> <p>
When signing comments, When signing comments,
@ -1128,10 +1152,13 @@ Robert Brown
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
Be specific when indicating times or software releases Be specific when indicating times or software releases
in a TODO comment: in a TODO comment and use
<a HREF="http://www.w3.org/TR/NOTE-datetime">YYYY-MM-DD</a>
format for dates to make automated processing of such dates easier,
e.g., 2038-01-20 for the end of the 32-bit signed <code>time_t</code>.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
;;--- TODO(brown): Remove this code after release 1.7 or before November, 2012. ;;--- TODO(brown): Remove this code after release 1.7 or before 2012-11-30.
</CODE_SNIPPET> </CODE_SNIPPET>
<p> <p>
For code that uses unobvious forms to accomplish a task, you must include a comment For code that uses unobvious forms to accomplish a task, you must include a comment
@ -3674,7 +3701,7 @@ Robert Brown
which matters a lot on non-Unix platforms which matters a lot on non-Unix platforms
(and even on some Unix implementations). (and even on some Unix implementations).
You probably should be using You probably should be using
<code>UIOP:MERGE-PATHNAMES*</code> <code>UIOP:MERGE-PATHNAMES*</code> or <code>UIOP:SUBPATHNAME</code>
instead of <code>MERGE-PATHNAMES</code>, instead of <code>MERGE-PATHNAMES</code>,
especially if your expectations for relative pathnames especially if your expectations for relative pathnames
are informed by the way they work in Unix or Windows; are informed by the way they work in Unix or Windows;
@ -3690,7 +3717,10 @@ Robert Brown
is not portable across implementations is not portable across implementations
in how it handles wildcards, sub-directories, symlinks, etc. in how it handles wildcards, sub-directories, symlinks, etc.
There again, <code>UIOP</code> provides several There again, <code>UIOP</code> provides several
common abstractions to deal with pathnames. common abstractions to deal with pathnames,
but only does so good a job.
For a complete portable solution, use IOLib —
though its Windows support lags behind.
</p> </p>
<p> <p>
<code>LOGICAL-PATHNAME</code>s are not a portable abstraction, <code>LOGICAL-PATHNAME</code>s are not a portable abstraction,
@ -3716,7 +3746,7 @@ Robert Brown
to forget irrelevant build-time paths and to forget irrelevant build-time paths and
reinitialize any search path from current environment variables. reinitialize any search path from current environment variables.
<code>ASDF</code> for instance requires you to reset its paths <code>ASDF</code> for instance requires you to reset its paths
with <code>ASDF:CLEAR-CONFIGURATION</code>. with <code>UIOP:CLEAR-CONFIGURATION</code>.
<code>UIOP</code> provides hooks <code>UIOP</code> provides hooks
to call functions before an image is dumped, to call functions before an image is dumped,
from which to reset or <code>makunbound</code> relevant variables. from which to reset or <code>makunbound</code> relevant variables.
@ -3840,7 +3870,7 @@ Robert Brown
</small> </small>
<p align="right"> <p align="right">
Revision 1.23 Revision 1.28
</p> </p>