diff --git a/lispguide.xml b/lispguide.xml index 5bde239..4a5af54 100644 --- a/lispguide.xml +++ b/lispguide.xml @@ -5,7 +5,7 @@
-Revision 1.15 +Revision 1.16
@@ -50,23 +50,22 @@ Robert BrownThis guide recommends formatting and stylistic choices designed to make your code easier for other people to understand. - Its guidelines apply to all the Common Lisp code we write at Google, - including our internal applications as well as - free software libraries we maintain and publish. - If you contribute to this code base, - you must follow these guidelines before you submit your patch, - or your code will be fixed to follow the guidelines after you do. + For those internal applications and free software libraries that + we develop at Google, + you should keep within these guidelines when making changes. + Note however that each project has its own rules and customs + that complement or override these general guidelines; + the speed-oriented QPX low fare search engine notably + has a very different style and feel from the QRes reservation system.
If you're writing Common Lisp code outside Google, - we invite you to consider the guidelines we expound in this guide. - You may apply some or all of them to your own projects, at your leisure: - we hope you find them as useful as we do. - Even if you don't, we welcome remarks and constructive feedback - you may have on how to improve our guide, and - what alternate styles work are successful for you. - Finally, we hope that our guide will inspire useful thoughts - in hackers who read it, especially so newcomers to Common Lisp. + we invite you to consider these guidelines. + You may find some of them useful + where they don't conflict with other priorities you have. + We welcome remarks and constructive feedback + on how to improve our guide, and + on what alternate styles work for you and why.
@@ -3031,7 +3030,7 @@ Robert Brown and make sure not to leak sensitive data this way. These are meant for interactive use, and can cause interesting damage - if they cause data or control leak to attackers. + if they cause data or control to leak to attackers.
You must not use gratuitous single quotes in CASE
forms.
@@ -3556,7 +3555,7 @@ Robert Brown
and does not risk going beyond CALL-ARGUMENTS-LIMIT
on implementations where that limit is small,
which could blow away the stack on long lists
- (we want our code to not be gratuitously unportable).
+ (we want to avoid gratuitous non-portability in our code).
However, you must be careful not to use REDUCE
@@ -3588,18 +3587,18 @@ Robert Brown
when you need to update a variable.
You should probably not depend on games
being played with the CDR
- of the current cons cell;
- and if you do, you must include a prominent
+ of the current CONS cell
+ (which some might argue is suggested but not guaranteed by the specification);
+ if you do, you must include a prominent
comment explaining the use of NCONC
;
- and you should probably reconsider your data representation.
+ and you should probably reconsider your data representation strategy.
By extension, you should avoid MAPCAN
or the NCONC
feature of LOOP
.
You should instead respectively use
ALEXANDRIA:MAPPEND
- and the APPEND
feature of LOOP
- respectively.
+ and the APPEND
feature of LOOP
.
NCONC
is very seldom a good idea,
@@ -3626,7 +3625,8 @@ Robert Brown
where the use of lists as a data structure has been vetted
because these lists are known to be short,
and when the function or expression the result of which are accumulated
- explicitly promises in its contract that it only returns fresh lists.
+ explicitly promises in its contract that it only returns fresh lists
+ (in particular, it can't be a constant quote or backquote expression).
Even then, the use of such primitives must be rare,
and accompanied by justifying documentation.
#'symbol
vs 'symbol
,
it is only a syntactic difference with no semantic impact,
except that the former works on Genera and the latter doesn't.
+
You must use the former style if your code is intended as a library
with maximal compatibility to all Common Lisp implementations;
otherwise, it is optional which style you use.
@@ -3886,7 +3887,7 @@ Robert Brown
-Revision 1.15 +Revision 1.16