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 Brown

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.

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.

@@ -3673,6 +3673,7 @@ Robert Brown Unlike the case of #'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