Google Common Lisp Style Guide, revision 1.16

lispguide.xml

@@ -5,7 +5,7 @@
 
 <p align="right">
 
-Revision 1.15
+Revision 1.16
 </p>
 
 
@@ -50,23 +50,22 @@ Robert Brown
   <p>
     This 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.
   </p>
   <p>
     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.
   </p>
   
   <p>
@@ -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.
       </p>
       <p>
         You must not use gratuitous single quotes in <code>CASE</code> forms.
@@ -3556,7 +3555,7 @@ Robert Brown
         and does not risk going beyond <code>CALL-ARGUMENTS-LIMIT</code>
         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).
       </p>
       <p>
         However, you must be careful not to use <code>REDUCE</code>
@@ -3588,18 +3587,18 @@ Robert Brown
         when you need to update a variable.
         You should probably not depend on games
         being played with the <code>CDR</code>
-        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 <code>NCONC</code>;
-        and you should probably reconsider your data representation.
+        and you should probably reconsider your data representation strategy.
       </p>
       <p>
         By extension, you should avoid <code>MAPCAN</code>
         or the <code>NCONC</code> feature of <code>LOOP</code>.
         You should instead respectively use
         <code>ALEXANDRIA:MAPPEND</code>
-        and the <code>APPEND</code> feature of <code>LOOP</code>
-        respectively.
+        and the <code>APPEND</code> feature of <code>LOOP</code>.
       </p>
       <p>
         <code>NCONC</code> 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.
       </p>
@@ -3673,6 +3673,7 @@ Robert Brown
         Unlike the case of <code>#'symbol</code> vs <code>'symbol</code>,
         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
 </small>
 
 <p align="right">
-Revision 1.15
+Revision 1.16
 </p>