1*8c35d5eeSXin Li<?xml version="1.0"?> 2*8c35d5eeSXin Li<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?> 3*8c35d5eeSXin Li<GUIDE title="Google Common Lisp Style Guide"> 4*8c35d5eeSXin Li 5*8c35d5eeSXin Li 6*8c35d5eeSXin Li<p align="right"> 7*8c35d5eeSXin Li 8*8c35d5eeSXin LiRevision 1.28 9*8c35d5eeSXin Li</p> 10*8c35d5eeSXin Li 11*8c35d5eeSXin Li 12*8c35d5eeSXin Li<address> 13*8c35d5eeSXin LiRobert Brown 14*8c35d5eeSXin Li</address> 15*8c35d5eeSXin Li<address> 16*8c35d5eeSXin Li <a HREF="mailto:[email protected]">François-René Rideau</a> 17*8c35d5eeSXin Li</address> 18*8c35d5eeSXin Li 19*8c35d5eeSXin Li<address> 20*8c35d5eeSXin Li In memoriam Dan Weinreb 21*8c35d5eeSXin Li</address> 22*8c35d5eeSXin Li 23*8c35d5eeSXin Li<p align="center"> 24*8c35d5eeSXin Li<cite>Patterns mean "I have run out of language."</cite> — Rich Hickey 25*8c35d5eeSXin Li</p> 26*8c35d5eeSXin Li 27*8c35d5eeSXin Li 28*8c35d5eeSXin Li<OVERVIEW> 29*8c35d5eeSXin Li<CATEGORY title="Important Note"> 30*8c35d5eeSXin Li <STYLEPOINT title="Note: Displaying Hidden Details in this Guide"> 31*8c35d5eeSXin Li <SUMMARY> 32*8c35d5eeSXin Li This style guide contains many details 33*8c35d5eeSXin Li that are initially hidden from view. 34*8c35d5eeSXin Li They are marked by the triangle icon, which you see here on your left. 35*8c35d5eeSXin Li Click it now. You should see "Hooray" appear below. 36*8c35d5eeSXin Li </SUMMARY> 37*8c35d5eeSXin Li <BODY> 38*8c35d5eeSXin Li <p> 39*8c35d5eeSXin Li Hooray! Now you know you can expand points to get more details. 40*8c35d5eeSXin Li Alternatively, there's an "expand all" at the top of this document. 41*8c35d5eeSXin Li </p> 42*8c35d5eeSXin Li </BODY> 43*8c35d5eeSXin Li </STYLEPOINT> 44*8c35d5eeSXin Li</CATEGORY> 45*8c35d5eeSXin Li<CATEGORY title="Background"> 46*8c35d5eeSXin Li <p> 47*8c35d5eeSXin Li Common Lisp is a powerful multiparadigm programming language. 48*8c35d5eeSXin Li With great power comes great responsibility. 49*8c35d5eeSXin Li </p> 50*8c35d5eeSXin Li <p> 51*8c35d5eeSXin Li This guide recommends formatting and stylistic choices 52*8c35d5eeSXin Li designed to make your code easier for other people to understand. 53*8c35d5eeSXin Li For those internal applications and free software libraries that 54*8c35d5eeSXin Li we develop at Google, 55*8c35d5eeSXin Li you should keep within these guidelines when making changes. 56*8c35d5eeSXin Li Note however that each project has its own rules and customs 57*8c35d5eeSXin Li that complement or override these general guidelines; 58*8c35d5eeSXin Li the speed-oriented QPX low fare search engine notably 59*8c35d5eeSXin Li has a very different style and feel from the QRes reservation system. 60*8c35d5eeSXin Li </p> 61*8c35d5eeSXin Li <p> 62*8c35d5eeSXin Li If you're writing Common Lisp code outside Google, 63*8c35d5eeSXin Li we invite you to consider these guidelines. 64*8c35d5eeSXin Li You may find some of them useful 65*8c35d5eeSXin Li where they don't conflict with other priorities you have. 66*8c35d5eeSXin Li We welcome remarks and constructive feedback 67*8c35d5eeSXin Li on how to improve our guide, and 68*8c35d5eeSXin Li on what alternate styles work for you and why. 69*8c35d5eeSXin Li </p> 70*8c35d5eeSXin Li 71*8c35d5eeSXin Li <p> 72*8c35d5eeSXin Li This guide is not a Common Lisp tutorial. 73*8c35d5eeSXin Li For basic information about the language, please consult 74*8c35d5eeSXin Li <a HREF="http://www.gigamonkeys.com/book/">Practical Common Lisp</a>. 75*8c35d5eeSXin Li For a language reference, please consult the 76*8c35d5eeSXin Li <a HREF="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">Common Lisp HyperSpec</a>. 77*8c35d5eeSXin Li For more detailed style guidance, take (with a pinch of salt) 78*8c35d5eeSXin Li a look at Peter Norvig and Kent Pitman's 79*8c35d5eeSXin Li <a HREF="http://norvig.com/luv-slides.ps">style guide</a>. 80*8c35d5eeSXin Li </p> 81*8c35d5eeSXin Li</CATEGORY> 82*8c35d5eeSXin Li</OVERVIEW> 83*8c35d5eeSXin Li<CATEGORY title="Meta-Guide"> 84*8c35d5eeSXin Li <STYLEPOINT title="Must, Should, May, or Not"> 85*8c35d5eeSXin Li <SUMMARY> 86*8c35d5eeSXin Li Each guideline's level of importance is indicated 87*8c35d5eeSXin Li by use of the following keywords and phrases, adapted from 88*8c35d5eeSXin Li <a href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>. 89*8c35d5eeSXin Li </SUMMARY> 90*8c35d5eeSXin Li <BODY> 91*8c35d5eeSXin Li <table> 92*8c35d5eeSXin Li <tr> 93*8c35d5eeSXin Li <th valign="top">MUST</th> 94*8c35d5eeSXin Li <td> 95*8c35d5eeSXin Li <p> 96*8c35d5eeSXin Li This word, or the terms "REQUIRED" or "SHALL", 97*8c35d5eeSXin Li means that the guideline is an absolute requirement. 98*8c35d5eeSXin Li You must ask permission to violate a MUST. 99*8c35d5eeSXin Li </p> 100*8c35d5eeSXin Li </td> 101*8c35d5eeSXin Li </tr> 102*8c35d5eeSXin Li <tr> 103*8c35d5eeSXin Li <th valign="top">MUST NOT</th> 104*8c35d5eeSXin Li <td> 105*8c35d5eeSXin Li <p> 106*8c35d5eeSXin Li This phrase, or the phrase "SHALL NOT", 107*8c35d5eeSXin Li means that the guideline is an absolute prohibition. 108*8c35d5eeSXin Li You must ask permission to violate a MUST NOT. 109*8c35d5eeSXin Li </p> 110*8c35d5eeSXin Li </td> 111*8c35d5eeSXin Li </tr> 112*8c35d5eeSXin Li <tr> 113*8c35d5eeSXin Li <th valign="top">SHOULD</th> 114*8c35d5eeSXin Li <td> 115*8c35d5eeSXin Li <p> 116*8c35d5eeSXin Li This word, or the adjective "RECOMMENDED", means that 117*8c35d5eeSXin Li there may exist valid reasons in particular circumstances 118*8c35d5eeSXin Li to ignore the demands of the guideline, but 119*8c35d5eeSXin Li the full implications must be understood and carefully weighed 120*8c35d5eeSXin Li before choosing a different course. 121*8c35d5eeSXin Li You must ask forgiveness for violating a SHOULD. 122*8c35d5eeSXin Li </p> 123*8c35d5eeSXin Li </td> 124*8c35d5eeSXin Li </tr> 125*8c35d5eeSXin Li <tr> 126*8c35d5eeSXin Li <th valign="top">SHOULD NOT</th> 127*8c35d5eeSXin Li <td> 128*8c35d5eeSXin Li <p> 129*8c35d5eeSXin Li This phrase, or the phrase "NOT RECOMMENDED", means that 130*8c35d5eeSXin Li there may exist valid reasons in particular circumstances 131*8c35d5eeSXin Li to ignore the prohibitions of this guideline, but 132*8c35d5eeSXin Li the full implications should be understood and carefully weighed 133*8c35d5eeSXin Li before choosing a different course. 134*8c35d5eeSXin Li You must ask forgiveness for violating a SHOULD NOT. 135*8c35d5eeSXin Li </p> 136*8c35d5eeSXin Li </td> 137*8c35d5eeSXin Li </tr> 138*8c35d5eeSXin Li <tr> 139*8c35d5eeSXin Li <th valign="top">MAY</th> 140*8c35d5eeSXin Li <td> 141*8c35d5eeSXin Li <p> 142*8c35d5eeSXin Li This word, or the adjective "OPTIONAL", 143*8c35d5eeSXin Li means that an item is truly optional. 144*8c35d5eeSXin Li </p> 145*8c35d5eeSXin Li </td> 146*8c35d5eeSXin Li </tr> 147*8c35d5eeSXin Li </table> 148*8c35d5eeSXin Li <p> 149*8c35d5eeSXin Li Unlike RFCs, we don't capitalize every instance of one of the above 150*8c35d5eeSXin Li keywords when it is used. 151*8c35d5eeSXin Li </p> 152*8c35d5eeSXin Li </BODY> 153*8c35d5eeSXin Li </STYLEPOINT> 154*8c35d5eeSXin Li <STYLEPOINT title="Permission and Forgiveness"> 155*8c35d5eeSXin Li <SUMMARY> 156*8c35d5eeSXin Li There are cases where transgression of some of these rules 157*8c35d5eeSXin Li is useful or even necessary. 158*8c35d5eeSXin Li In some cases, you must seek permission or obtain forgiveness 159*8c35d5eeSXin Li from the proper people. 160*8c35d5eeSXin Li </SUMMARY> 161*8c35d5eeSXin Li <BODY> 162*8c35d5eeSXin Li <p> 163*8c35d5eeSXin Li Permission comes from the owners of your project. 164*8c35d5eeSXin Li </p> 165*8c35d5eeSXin Li 166*8c35d5eeSXin Li <p> 167*8c35d5eeSXin Li Forgiveness is requested in a comment 168*8c35d5eeSXin Li near the point of guideline violation, 169*8c35d5eeSXin Li and is granted by your code reviewer. 170*8c35d5eeSXin Li The original comment should be signed by you, and 171*8c35d5eeSXin Li the reviewer should add a signed approval to the comment at review time. 172*8c35d5eeSXin Li </p> 173*8c35d5eeSXin Li 174*8c35d5eeSXin Li </BODY> 175*8c35d5eeSXin Li </STYLEPOINT> 176*8c35d5eeSXin Li <STYLEPOINT title="Conventions"> 177*8c35d5eeSXin Li <SUMMARY> 178*8c35d5eeSXin Li You MUST follow conventions. They are not optional. 179*8c35d5eeSXin Li </SUMMARY> 180*8c35d5eeSXin Li <BODY> 181*8c35d5eeSXin Li <p> 182*8c35d5eeSXin Li Some of these guidelines are motivated by universal principles of good programming. 183*8c35d5eeSXin Li Some guidelines are motivated by technical peculiarities of Common Lisp. 184*8c35d5eeSXin Li Some guidelines were once motivated by a technical reason, 185*8c35d5eeSXin Li but the guideline remained after the reason subsided. 186*8c35d5eeSXin Li Some guidelines, such those about as comments and indentation, 187*8c35d5eeSXin Li are based purely on convention, rather than on clear technical merit. 188*8c35d5eeSXin Li Whatever the case may be, you must still follow these guidelines, 189*8c35d5eeSXin Li as well as other conventional guidelines 190*8c35d5eeSXin Li that have not been formalized in this document. 191*8c35d5eeSXin Li </p> 192*8c35d5eeSXin Li <p> 193*8c35d5eeSXin Li You MUST follow conventions. 194*8c35d5eeSXin Li They are important for readability. 195*8c35d5eeSXin Li When conventions are followed by default, 196*8c35d5eeSXin Li violations of the convention are a signal 197*8c35d5eeSXin Li that something notable is happening and deserves attention. 198*8c35d5eeSXin Li When conventions are systematically violated, 199*8c35d5eeSXin Li violations of the convention are a distracting noise 200*8c35d5eeSXin Li that needs to be ignored. 201*8c35d5eeSXin Li </p> 202*8c35d5eeSXin Li <p> 203*8c35d5eeSXin Li Conventional guidelines <em>are</em> indoctrination. 204*8c35d5eeSXin Li Their purpose is to make you follow the mores of the community, 205*8c35d5eeSXin Li 206*8c35d5eeSXin Li so you can more effectively cooperate with existing members. 207*8c35d5eeSXin Li It is still useful to distinguish the parts that are technically motivated 208*8c35d5eeSXin Li from the parts that are mere conventions, 209*8c35d5eeSXin Li so you know when best to defy conventions for good effect, 210*8c35d5eeSXin Li and when not to fall into the pitfalls that the conventions are there to help avoid. 211*8c35d5eeSXin Li </p> 212*8c35d5eeSXin Li </BODY> 213*8c35d5eeSXin Li </STYLEPOINT> 214*8c35d5eeSXin Li <STYLEPOINT title="Old Code"> 215*8c35d5eeSXin Li <SUMMARY> 216*8c35d5eeSXin Li Fix old code as you go. 217*8c35d5eeSXin Li </SUMMARY> 218*8c35d5eeSXin Li <BODY> 219*8c35d5eeSXin Li <p> 220*8c35d5eeSXin Li A lot of our code was written before these guidelines existed. 221*8c35d5eeSXin Li You should fix violations as you encounter them 222*8c35d5eeSXin Li in the course of your normal coding. 223*8c35d5eeSXin Li </p> 224*8c35d5eeSXin Li <p> 225*8c35d5eeSXin Li You must not fix violations en masse 226*8c35d5eeSXin Li without warning other developers and coordinating with them, 227*8c35d5eeSXin Li so as not to make the merging of large branches 228*8c35d5eeSXin Li more difficult than it already is. 229*8c35d5eeSXin Li </p> 230*8c35d5eeSXin Li </BODY> 231*8c35d5eeSXin Li </STYLEPOINT> 232*8c35d5eeSXin Li <STYLEPOINT title="Future Topics"> 233*8c35d5eeSXin Li <SUMMARY> 234*8c35d5eeSXin Li There are many topics for additional standardization 235*8c35d5eeSXin Li not covered by current version of this document, 236*8c35d5eeSXin Li but deferred to future versions. 237*8c35d5eeSXin Li </SUMMARY> 238*8c35d5eeSXin Li <BODY> 239*8c35d5eeSXin Li <ul> 240*8c35d5eeSXin Li <li> 241*8c35d5eeSXin Li File and directory structure 242*8c35d5eeSXin Li </li> 243*8c35d5eeSXin Li <li> 244*8c35d5eeSXin Li Packages and modularity 245*8c35d5eeSXin Li </li> 246*8c35d5eeSXin Li <li> 247*8c35d5eeSXin Li Threads and locking 248*8c35d5eeSXin Li </li> 249*8c35d5eeSXin Li <li> 250*8c35d5eeSXin Li How to add configurable components 251*8c35d5eeSXin Li </li> 252*8c35d5eeSXin Li <li> 253*8c35d5eeSXin Li CLOS style: initforms, slot and accessor names, etc. 254*8c35d5eeSXin Li </li> 255*8c35d5eeSXin Li <li> 256*8c35d5eeSXin Li Recommendations on max number of slots per class. 257*8c35d5eeSXin Li </li> 258*8c35d5eeSXin Li <li> 259*8c35d5eeSXin Li More concrete examples of good code: 260*8c35d5eeSXin Li <ul> 261*8c35d5eeSXin Li <li> 262*8c35d5eeSXin Li exceptions 263*8c35d5eeSXin Li </li> 264*8c35d5eeSXin Li <li> 265*8c35d5eeSXin Li transactions, with retry 266*8c35d5eeSXin Li </li> 267*8c35d5eeSXin Li <li> 268*8c35d5eeSXin Li XML 269*8c35d5eeSXin Li </li> 270*8c35d5eeSXin Li <li> 271*8c35d5eeSXin Li typing 272*8c35d5eeSXin Li </li> 273*8c35d5eeSXin Li <li> 274*8c35d5eeSXin Li encapsulation / abstraction 275*8c35d5eeSXin Li </li> 276*8c35d5eeSXin Li <li> 277*8c35d5eeSXin Li class and slot names 278*8c35d5eeSXin Li </li> 279*8c35d5eeSXin Li <li> 280*8c35d5eeSXin Li etc. 281*8c35d5eeSXin Li </li> 282*8c35d5eeSXin Li </ul> 283*8c35d5eeSXin Li </li> 284*8c35d5eeSXin Li <li> 285*8c35d5eeSXin Li When (not) to use conditional compilation: 286*8c35d5eeSXin Li <ul> 287*8c35d5eeSXin Li <li> 288*8c35d5eeSXin Li modifying the product 289*8c35d5eeSXin Li </li> 290*8c35d5eeSXin Li <li> 291*8c35d5eeSXin Li conditional debugging/console output/etc. 292*8c35d5eeSXin Li </li> 293*8c35d5eeSXin Li <li> 294*8c35d5eeSXin Li "temporarily" commenting-out blocks of code 295*8c35d5eeSXin Li </li> 296*8c35d5eeSXin Li <li> 297*8c35d5eeSXin Li etc. 298*8c35d5eeSXin Li </li> 299*8c35d5eeSXin Li </ul> 300*8c35d5eeSXin Li </li> 301*8c35d5eeSXin Li </ul> 302*8c35d5eeSXin Li </BODY> 303*8c35d5eeSXin Li </STYLEPOINT> 304*8c35d5eeSXin Li </CATEGORY> 305*8c35d5eeSXin Li<CATEGORY title="General Guidelines"> 306*8c35d5eeSXin Li <STYLEPOINT title="Principles"> 307*8c35d5eeSXin Li <SUMMARY> 308*8c35d5eeSXin Li There are some basic principles for team software development 309*8c35d5eeSXin Li that every developer must keep in mind. 310*8c35d5eeSXin Li Whenever the detailed guidelines are inadequate, confusing or contradictory, 311*8c35d5eeSXin Li refer back to these principles for guidance: 312*8c35d5eeSXin Li <ul> 313*8c35d5eeSXin Li <li> 314*8c35d5eeSXin Li Every developer's code must be easy for another developer 315*8c35d5eeSXin Li to read, understand, and modify 316*8c35d5eeSXin Li — even if the first developer isn't around to explain it. 317*8c35d5eeSXin Li (This is the "hit by a truck" principle.) 318*8c35d5eeSXin Li </li> 319*8c35d5eeSXin Li <li> 320*8c35d5eeSXin Li Everybody's code should look the same. 321*8c35d5eeSXin Li Ideally, there should be no way to look at lines of code 322*8c35d5eeSXin Li and recognize it as "Fred's code" by its style. 323*8c35d5eeSXin Li </li> 324*8c35d5eeSXin Li <li> 325*8c35d5eeSXin Li Be precise. 326*8c35d5eeSXin Li </li> 327*8c35d5eeSXin Li <li> 328*8c35d5eeSXin Li Be concise. 329*8c35d5eeSXin Li </li> 330*8c35d5eeSXin Li <li> 331*8c35d5eeSXin Li KISS — Keep It Simple, Stupid. 332*8c35d5eeSXin Li </li> 333*8c35d5eeSXin Li <li> 334*8c35d5eeSXin Li Use the smallest hammer for the job. 335*8c35d5eeSXin Li </li> 336*8c35d5eeSXin Li <li> 337*8c35d5eeSXin Li Use common sense. 338*8c35d5eeSXin Li </li> 339*8c35d5eeSXin Li <li> 340*8c35d5eeSXin Li Keep related code together. 341*8c35d5eeSXin Li Minimize the amount of jumping around 342*8c35d5eeSXin Li someone has to do to understand an area of code. 343*8c35d5eeSXin Li </li> 344*8c35d5eeSXin Li </ul> 345*8c35d5eeSXin Li </SUMMARY> 346*8c35d5eeSXin Li <BODY> 347*8c35d5eeSXin Li </BODY> 348*8c35d5eeSXin Li </STYLEPOINT> 349*8c35d5eeSXin Li <STYLEPOINT title="Priorities"> 350*8c35d5eeSXin Li <SUMMARY> 351*8c35d5eeSXin Li <p> 352*8c35d5eeSXin Li When making decisions about how to write a given piece of 353*8c35d5eeSXin Li code, aim for the following -ilities in this priority order: 354*8c35d5eeSXin Li </p> 355*8c35d5eeSXin Li <ul> 356*8c35d5eeSXin Li <li> 357*8c35d5eeSXin Li Usability by the customer 358*8c35d5eeSXin Li </li> 359*8c35d5eeSXin Li <li> 360*8c35d5eeSXin Li Debuggability/Testability 361*8c35d5eeSXin Li </li> 362*8c35d5eeSXin Li <li> 363*8c35d5eeSXin Li Readability/Comprehensibility 364*8c35d5eeSXin Li </li> 365*8c35d5eeSXin Li <li> 366*8c35d5eeSXin Li Extensibility/Modifiability 367*8c35d5eeSXin Li </li> 368*8c35d5eeSXin Li <li> 369*8c35d5eeSXin Li Efficiency (of the Lisp code at runtime) 370*8c35d5eeSXin Li </li> 371*8c35d5eeSXin Li </ul> 372*8c35d5eeSXin Li </SUMMARY> 373*8c35d5eeSXin Li <BODY> 374*8c35d5eeSXin Li <p> 375*8c35d5eeSXin Li Most of these are obvious. 376*8c35d5eeSXin Li </p> 377*8c35d5eeSXin Li <p> 378*8c35d5eeSXin Li Usability by the customer means that the system has to do what the 379*8c35d5eeSXin Li customer requires; it has to handle the customer's transaction 380*8c35d5eeSXin Li volumes, uptime requirements; etc. 381*8c35d5eeSXin Li </p> 382*8c35d5eeSXin Li <p> 383*8c35d5eeSXin Li For the Lisp efficiency point, 384*8c35d5eeSXin Li given two options of equivalent complexity, 385*8c35d5eeSXin Li pick the one that performs better. 386*8c35d5eeSXin Li (This is often the same as the one that conses less, 387*8c35d5eeSXin Li i.e. allocates less storage from the heap.) 388*8c35d5eeSXin Li </p> 389*8c35d5eeSXin Li <p> 390*8c35d5eeSXin Li Given two options where one is more complex than the other, 391*8c35d5eeSXin Li pick the simpler option and revisit the decision only if 392*8c35d5eeSXin Li profiling shows it to be a performance bottleneck. 393*8c35d5eeSXin Li </p> 394*8c35d5eeSXin Li <p> 395*8c35d5eeSXin Li However, avoid premature optimization. 396*8c35d5eeSXin Li Don't add complexity to speed up something that runs rarely, 397*8c35d5eeSXin Li since in the long run, it matters less whether such code is fast. 398*8c35d5eeSXin Li </p> 399*8c35d5eeSXin Li </BODY> 400*8c35d5eeSXin Li </STYLEPOINT> 401*8c35d5eeSXin Li <STYLEPOINT title="Architecture"> 402*8c35d5eeSXin Li <SUMMARY> 403*8c35d5eeSXin Li To build code that is robust and maintainable, 404*8c35d5eeSXin Li it matters a lot how the code is divided into components, 405*8c35d5eeSXin Li how these components communicate, 406*8c35d5eeSXin Li how changes propagate as they evolve, 407*8c35d5eeSXin Li and more importantly 408*8c35d5eeSXin Li how the programmers who develop these components communicate 409*8c35d5eeSXin Li as these components evolve. 410*8c35d5eeSXin Li </SUMMARY> 411*8c35d5eeSXin Li <BODY> 412*8c35d5eeSXin Li <p> 413*8c35d5eeSXin Li If your work affects other groups, might be reusable across groups, 414*8c35d5eeSXin Li adds new components, has an impact on other groups 415*8c35d5eeSXin Li (including QA or Ops), or otherwise isn't purely local, 416*8c35d5eeSXin Li you must write it up using at least a couple of paragraphs, 417*8c35d5eeSXin Li and get a design approval from the other parties involved 418*8c35d5eeSXin Li before starting to write code — or be ready to scratch what you have 419*8c35d5eeSXin Li when they object. 420*8c35d5eeSXin Li </p> 421*8c35d5eeSXin Li <p> 422*8c35d5eeSXin Li If you don't know or don't care about these issues, 423*8c35d5eeSXin Li ask someone who does. 424*8c35d5eeSXin Li </p> 425*8c35d5eeSXin Li </BODY> 426*8c35d5eeSXin Li </STYLEPOINT> 427*8c35d5eeSXin Li <STYLEPOINT title="Using Libraries"> 428*8c35d5eeSXin Li <SUMMARY> 429*8c35d5eeSXin Li Often, the smallest hammer is to use an existing library. 430*8c35d5eeSXin Li Or one that doesn't exist yet. 431*8c35d5eeSXin Li In such cases, you are encouraged to use or develop such a library, 432*8c35d5eeSXin Li but you must take appropriate precautions. 433*8c35d5eeSXin Li </SUMMARY> 434*8c35d5eeSXin Li <BODY> 435*8c35d5eeSXin Li <ul> 436*8c35d5eeSXin Li <li> 437*8c35d5eeSXin Li You MUST NOT start a new library 438*8c35d5eeSXin Li unless you established that none is already available 439*8c35d5eeSXin Li that can be fixed or completed into becoming what you need. 440*8c35d5eeSXin Li That's a rule against the NIH syndrome ("Not Invented Here"), 441*8c35d5eeSXin Li which is particularly strong amongst Lisp hackers. 442*8c35d5eeSXin Li </li> 443*8c35d5eeSXin Li <li> 444*8c35d5eeSXin Li Whichever library, old or new, you pick, you MUST get permission 445*8c35d5eeSXin Li to incorporate third-party code into the code base. 446*8c35d5eeSXin Li You must discuss the use of such library 447*8c35d5eeSXin Li in the appropriate mailing-list, 448*8c35d5eeSXin Li and have your code reviewed by people knowledgeable in the domain 449*8c35d5eeSXin Li and/or the Lisp library ecosystem (if any). 450*8c35d5eeSXin Li Please be ready to argue why this particular solution makes sense 451*8c35d5eeSXin Li as compared to other available libraries. 452*8c35d5eeSXin Li </li> 453*8c35d5eeSXin Li <li> 454*8c35d5eeSXin Li Some libraries are distributed under licenses not compatible 455*8c35d5eeSXin Li with the software you're writing, and 456*8c35d5eeSXin Li must not be considered available for use. 457*8c35d5eeSXin Li Be aware of these issues, or consult with people who are. 458*8c35d5eeSXin Li </li> 459*8c35d5eeSXin Li </ul> 460*8c35d5eeSXin Li 461*8c35d5eeSXin Li </BODY> 462*8c35d5eeSXin Li </STYLEPOINT> 463*8c35d5eeSXin Li <STYLEPOINT title="Open-Sourcing Code"> 464*8c35d5eeSXin Li <SUMMARY> 465*8c35d5eeSXin Li <p> 466*8c35d5eeSXin Li If you write a general-purpose library, 467*8c35d5eeSXin Li or modify an existing open-source library, 468*8c35d5eeSXin Li you are encouraged to publish the result 469*8c35d5eeSXin Li separate from your main project and then 470*8c35d5eeSXin Li have your project import it like any other open-source library. 471*8c35d5eeSXin Li </p> 472*8c35d5eeSXin Li 473*8c35d5eeSXin Li </SUMMARY> 474*8c35d5eeSXin Li <BODY> 475*8c35d5eeSXin Li <p> 476*8c35d5eeSXin Li Use your judgment to distinguish 477*8c35d5eeSXin Li general-purpose versus business-specific code, 478*8c35d5eeSXin Li and open-source the general-purpose parts, 479*8c35d5eeSXin Li while keeping the business-specific parts a trade secret. 480*8c35d5eeSXin Li </p> 481*8c35d5eeSXin Li 482*8c35d5eeSXin Li <p> 483*8c35d5eeSXin Li Open-Sourcing code has many advantages, 484*8c35d5eeSXin Li including being able to leverage third parties for development, 485*8c35d5eeSXin Li letting the development of features be user-directed, 486*8c35d5eeSXin Li and keeping you honest with respect to code quality. 487*8c35d5eeSXin Li Whatever code you write, you will have to maintain anyway, 488*8c35d5eeSXin Li and make sure its quality is high enough to sustain use in production. 489*8c35d5eeSXin Li There should therefore be no additional burden to Open-Sourcing, 490*8c35d5eeSXin Li even of code that (at least initially) 491*8c35d5eeSXin Li is not directly usable by third parties. 492*8c35d5eeSXin Li </p> 493*8c35d5eeSXin Li 494*8c35d5eeSXin Li </BODY> 495*8c35d5eeSXin Li </STYLEPOINT> 496*8c35d5eeSXin Li <STYLEPOINT title="Development Process"> 497*8c35d5eeSXin Li <SUMMARY> 498*8c35d5eeSXin Li Development process is outside the scope of this document. 499*8c35d5eeSXin Li However, developers should remember at least these bits: 500*8c35d5eeSXin Li get reviewed, write tests, eliminate warnings, run tests, avoid mass-changes. 501*8c35d5eeSXin Li </SUMMARY> 502*8c35d5eeSXin Li <BODY> 503*8c35d5eeSXin Li <p> 504*8c35d5eeSXin Li </p> 505*8c35d5eeSXin Li <ul> 506*8c35d5eeSXin Li <li> 507*8c35d5eeSXin Li All code changes must be reviewed. 508*8c35d5eeSXin Li You should expect that your code will be reviewed by other hackers, 509*8c35d5eeSXin Li and that you will be assigned other hackers' code to review. 510*8c35d5eeSXin Li Part of the review criteria will be that code obeys 511*8c35d5eeSXin Li the coding standards in this document. 512*8c35d5eeSXin Li </li> 513*8c35d5eeSXin Li <li> 514*8c35d5eeSXin Li You must write and check-in tests for new code that you write and old bugs you fix. 515*8c35d5eeSXin Li There must be a unit test for every API function, 516*8c35d5eeSXin Li and any previously failing case. 517*8c35d5eeSXin Li Your work is not truly done until this activity is complete. 518*8c35d5eeSXin Li Estimating tasks must include the time it takes to produce such tests. 519*8c35d5eeSXin Li </li> 520*8c35d5eeSXin Li <li> 521*8c35d5eeSXin Li Your code must compile 522*8c35d5eeSXin Li without any compilation error or warning messages whatsoever. 523*8c35d5eeSXin Li If the compiler issues warnings that should be ignored, 524*8c35d5eeSXin Li muffle those warnings using the 525*8c35d5eeSXin Li <code>UIOP:WITH-MUFFLED-COMPILER-CONDITIONS</code> and 526*8c35d5eeSXin Li <code>UIOP:*UNINTERESTING-COMPILER-CONDITIONS*</code> 527*8c35d5eeSXin Li framework (part of <code>UIOP</code>, part of <code>ASDF 3</code>), 528*8c35d5eeSXin Li either around the entire project, or around individual files 529*8c35d5eeSXin Li (using <code>ASDF</code>'s <code>:around-compile</code> hooks). 530*8c35d5eeSXin Li </li> 531*8c35d5eeSXin Li <li> 532*8c35d5eeSXin Li All code should be checked in an appropriate source control system, 533*8c35d5eeSXin Li in a way that allows for complete reproducibility of 534*8c35d5eeSXin Li build, test and execution of 535*8c35d5eeSXin Li the code that is, has been or may be deployed. 536*8c35d5eeSXin Li </li> 537*8c35d5eeSXin Li <li> 538*8c35d5eeSXin Li You must run the "precheckin" tests, and each component must pass 539*8c35d5eeSXin Li its unit tests successfully before you commit any code. 540*8c35d5eeSXin Li </li> 541*8c35d5eeSXin Li <li> 542*8c35d5eeSXin Li You should incorporate code coverage into your testing process. 543*8c35d5eeSXin Li Tests are not sufficient 544*8c35d5eeSXin Li if they do not cover all new and updated code; 545*8c35d5eeSXin Li code that for whatever reason cannot be included in coverage results 546*8c35d5eeSXin Li should be clearly marked as such including the reason. 547*8c35d5eeSXin Li </li> 548*8c35d5eeSXin Li <li> 549*8c35d5eeSXin Li Many people develop on branches. 550*8c35d5eeSXin Li You must get permission to undertake mass-changes 551*8c35d5eeSXin Li (e.g. mass reindentations) 552*8c35d5eeSXin Li so that we can coordinate in advance, 553*8c35d5eeSXin Li and give branch residents time to get back on the mainline 554*8c35d5eeSXin Li </li> 555*8c35d5eeSXin Li </ul> 556*8c35d5eeSXin Li </BODY> 557*8c35d5eeSXin Li </STYLEPOINT> 558*8c35d5eeSXin Li</CATEGORY> 559*8c35d5eeSXin Li<CATEGORY title="Formatting"> 560*8c35d5eeSXin Li <STYLEPOINT title="Spelling and Abbreviations"> 561*8c35d5eeSXin Li <SUMMARY> 562*8c35d5eeSXin Li <p> 563*8c35d5eeSXin Li You must use correct spelling in your comments, 564*8c35d5eeSXin Li and most importantly in your identifiers. 565*8c35d5eeSXin Li </p> 566*8c35d5eeSXin Li <p> 567*8c35d5eeSXin Li When several correct spellings exist (including American vs English), 568*8c35d5eeSXin Li and there isn't a consensus amongst developers as which to use, 569*8c35d5eeSXin Li you should choose the shorter spelling. 570*8c35d5eeSXin Li </p> 571*8c35d5eeSXin Li <p> 572*8c35d5eeSXin Li You must use only common and domain-specific abbreviations, and 573*8c35d5eeSXin Li must be consistent with these abbreviations. You may abbreviate 574*8c35d5eeSXin Li lexical variables of limited scope in order to avoid overly-long 575*8c35d5eeSXin Li symbol names. 576*8c35d5eeSXin Li </p> 577*8c35d5eeSXin Li </SUMMARY> 578*8c35d5eeSXin Li <BODY> 579*8c35d5eeSXin Li <p> 580*8c35d5eeSXin Li If you're not sure, consult a dictionary, 581*8c35d5eeSXin Li Google for alternative spellings, 582*8c35d5eeSXin Li or ask a local expert. 583*8c35d5eeSXin Li </p> 584*8c35d5eeSXin Li <p> 585*8c35d5eeSXin Li Here are examples of choosing the correct spelling: 586*8c35d5eeSXin Li </p> 587*8c35d5eeSXin Li <ul> 588*8c35d5eeSXin Li <li> 589*8c35d5eeSXin Li Use "complimentary" in the sense of a meal or beverage 590*8c35d5eeSXin Li that is not paid for by the recipient, not "complementary". 591*8c35d5eeSXin Li </li> 592*8c35d5eeSXin Li <li> 593*8c35d5eeSXin Li Use "existent" and "nonexistent", not "existant". 594*8c35d5eeSXin Li Use "existence", not "existance". 595*8c35d5eeSXin Li </li> 596*8c35d5eeSXin Li <li> 597*8c35d5eeSXin Li Use "hierarchy" not "heirarchy". 598*8c35d5eeSXin Li </li> 599*8c35d5eeSXin Li <li> 600*8c35d5eeSXin Li Use "precede" not "preceed". 601*8c35d5eeSXin Li </li> 602*8c35d5eeSXin Li <li> 603*8c35d5eeSXin Li Use "weird", not "wierd". 604*8c35d5eeSXin Li </li> 605*8c35d5eeSXin Li </ul> 606*8c35d5eeSXin Li <p> 607*8c35d5eeSXin Li Here are examples of choosing the shorter spelling: 608*8c35d5eeSXin Li </p> 609*8c35d5eeSXin Li <ul> 610*8c35d5eeSXin Li <li> 611*8c35d5eeSXin Li Use "canceled", not "cancelled" 612*8c35d5eeSXin Li </li> 613*8c35d5eeSXin Li <li> 614*8c35d5eeSXin Li Use "queuing", not "queueing". 615*8c35d5eeSXin Li </li> 616*8c35d5eeSXin Li <li> 617*8c35d5eeSXin Li Use "signaled", not "signalled"; 618*8c35d5eeSXin Li </li> 619*8c35d5eeSXin Li <li> 620*8c35d5eeSXin Li Use "traveled", not "travelled". 621*8c35d5eeSXin Li </li> 622*8c35d5eeSXin Li <li> 623*8c35d5eeSXin Li Use "aluminum", not "aluminium" 624*8c35d5eeSXin Li </li> 625*8c35d5eeSXin Li <li> 626*8c35d5eeSXin Li Use "oriented", not "orientated" 627*8c35d5eeSXin Li </li> 628*8c35d5eeSXin Li <li> 629*8c35d5eeSXin Li Use "color", not "colour" 630*8c35d5eeSXin Li </li> 631*8c35d5eeSXin Li <li> 632*8c35d5eeSXin Li Use "behavior", not "behaviour" 633*8c35d5eeSXin Li </li> 634*8c35d5eeSXin Li </ul> 635*8c35d5eeSXin Li <p> 636*8c35d5eeSXin Li Make appropriate exceptions for industry standard nomenclature/jargon, 637*8c35d5eeSXin Li including plain misspellings. 638*8c35d5eeSXin Li For instance: 639*8c35d5eeSXin Li </p> 640*8c35d5eeSXin Li <ul> 641*8c35d5eeSXin Li <li> 642*8c35d5eeSXin Li Use "referer", not "referrer", in the context of the HTTP protocol. 643*8c35d5eeSXin Li </li> 644*8c35d5eeSXin Li </ul> 645*8c35d5eeSXin Li 646*8c35d5eeSXin Li </BODY> 647*8c35d5eeSXin Li </STYLEPOINT> 648*8c35d5eeSXin Li <STYLEPOINT title="Line length"> 649*8c35d5eeSXin Li <SUMMARY> 650*8c35d5eeSXin Li You should format source code so that no line is longer than 100 characters. 651*8c35d5eeSXin Li </SUMMARY> 652*8c35d5eeSXin Li <BODY> 653*8c35d5eeSXin Li <p> 654*8c35d5eeSXin Li Some line length restriction is better than none at all. 655*8c35d5eeSXin Li While old text terminals used to make 80 columns the standard, 656*8c35d5eeSXin Li these days, allowing 100 columns seems better, 657*8c35d5eeSXin Li since good style encourages the use of 658*8c35d5eeSXin Li descriptive variables and function names. 659*8c35d5eeSXin Li </p> 660*8c35d5eeSXin Li 661*8c35d5eeSXin Li </BODY> 662*8c35d5eeSXin Li </STYLEPOINT> 663*8c35d5eeSXin Li <STYLEPOINT title="Indentation"> 664*8c35d5eeSXin Li <SUMMARY> 665*8c35d5eeSXin Li <p> 666*8c35d5eeSXin Li Indent your code the way a properly configured GNU Emacs does. 667*8c35d5eeSXin Li </p> 668*8c35d5eeSXin Li <p> 669*8c35d5eeSXin Li Maintain a consistent indentation style throughout a project. 670*8c35d5eeSXin Li </p> 671*8c35d5eeSXin Li <p> 672*8c35d5eeSXin Li Indent carefully to make the code easier to understand. 673*8c35d5eeSXin Li </p> 674*8c35d5eeSXin Li </SUMMARY> 675*8c35d5eeSXin Li <BODY> 676*8c35d5eeSXin Li <p> 677*8c35d5eeSXin Li Common Lisp indentation in Emacs is provided by the cl-indent library. 678*8c35d5eeSXin Li The latest version of cl-indent is packaged with 679*8c35d5eeSXin Li <a HREF="https://www.common-lisp.net/project/slime/">SLIME</a> 680*8c35d5eeSXin Li (under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs 681*8c35d5eeSXin Li to load SLIME automatically using 682*8c35d5eeSXin Li <a HREF="https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of 683*8c35d5eeSXin Li contrib libraries to be loaded in the call to slime-setup. 684*8c35d5eeSXin Li </p> 685*8c35d5eeSXin Li <p> 686*8c35d5eeSXin Li Ideally, use the default indentation settings provided by 687*8c35d5eeSXin Li slime-indentation. If necessary, customize indentation parameters to 688*8c35d5eeSXin Li maintain a consistent indentation style throughout an existing project. 689*8c35d5eeSXin Li Parameters can be customized using the :variables setting in 690*8c35d5eeSXin Li define-common-lisp-style. Indentation of specific forms can be 691*8c35d5eeSXin Li customized using the :indentation setting of define-common-lisp-style. 692*8c35d5eeSXin Li This is particularly useful when creating forms that behave like macros 693*8c35d5eeSXin Li or special operators that are indented differently than standard 694*8c35d5eeSXin Li function calls (e.g. defun, labels, or let). Add a 695*8c35d5eeSXin Li <a HREF="https://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 696*8c35d5eeSXin Li the appropriate style automatically. 697*8c35d5eeSXin Li </p> 698*8c35d5eeSXin Li 699*8c35d5eeSXin Li 700*8c35d5eeSXin Li <p> 701*8c35d5eeSXin Li Use indentation to make complex function applications easier to read. 702*8c35d5eeSXin Li When an application does not fit on one line 703*8c35d5eeSXin Li or the function takes many arguments, 704*8c35d5eeSXin Li consider inserting newlines between the arguments 705*8c35d5eeSXin Li so that each one is on a separate line. 706*8c35d5eeSXin Li However, do not insert newlines in a way that makes it hard to tell 707*8c35d5eeSXin Li how many arguments the function takes 708*8c35d5eeSXin Li or where an argument form starts and ends. 709*8c35d5eeSXin Li </p> 710*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 711*8c35d5eeSXin Li ;; Bad 712*8c35d5eeSXin Li (do-something first-argument second-argument (lambda (x) 713*8c35d5eeSXin Li (frob x)) fourth-argument last-argument) 714*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 715*8c35d5eeSXin Li <CODE_SNIPPET> 716*8c35d5eeSXin Li ;; Better 717*8c35d5eeSXin Li (do-something first-argument 718*8c35d5eeSXin Li second-argument 719*8c35d5eeSXin Li #'(lambda (x) (frob x)) 720*8c35d5eeSXin Li fourth-argument 721*8c35d5eeSXin Li last-argument) 722*8c35d5eeSXin Li </CODE_SNIPPET> 723*8c35d5eeSXin Li </BODY> 724*8c35d5eeSXin Li </STYLEPOINT> 725*8c35d5eeSXin Li <STYLEPOINT title="File Header"> 726*8c35d5eeSXin Li <SUMMARY> 727*8c35d5eeSXin Li <p> 728*8c35d5eeSXin Li You should include a description at the top of each source file. 729*8c35d5eeSXin Li </p> 730*8c35d5eeSXin Li <p> 731*8c35d5eeSXin Li You should include neither authorship nor copyright information in a source file. 732*8c35d5eeSXin Li </p> 733*8c35d5eeSXin Li </SUMMARY> 734*8c35d5eeSXin Li <BODY> 735*8c35d5eeSXin Li <p> 736*8c35d5eeSXin Li Every source file should begin with a brief description 737*8c35d5eeSXin Li of the contents of that file. 738*8c35d5eeSXin Li </p> 739*8c35d5eeSXin Li <p> 740*8c35d5eeSXin Li After that description, every file should start the code itself with an 741*8c35d5eeSXin Li <code>(in-package :<em>package-name</em>)</code> form. 742*8c35d5eeSXin Li </p> 743*8c35d5eeSXin Li <p> 744*8c35d5eeSXin Li After that <code>in-package</code> form, 745*8c35d5eeSXin Li every file should follow with any file-specific 746*8c35d5eeSXin Li <code>(declaim (optimize ...))</code> declaration 747*8c35d5eeSXin Li that is not covered by an <code>ASDF</code> <code>:around-compile</code> hook. 748*8c35d5eeSXin Li </p> 749*8c35d5eeSXin Li <CODE_SNIPPET> 750*8c35d5eeSXin Li ;;;; Variable length encoding for integers and floating point numbers. 751*8c35d5eeSXin Li 752*8c35d5eeSXin Li (in-package #:varint) 753*8c35d5eeSXin Li (declaim #.*optimize-default*) 754*8c35d5eeSXin Li </CODE_SNIPPET> 755*8c35d5eeSXin Li <p> 756*8c35d5eeSXin Li You should not include authorship information at the top of a file: 757*8c35d5eeSXin Li better information is available from version control, 758*8c35d5eeSXin Li and such a mention will only cause confusion and grief. 759*8c35d5eeSXin Li Indeed, whoever was the main author at the time such a mention was included 760*8c35d5eeSXin Li might not be who eventually made the most significant contributions to the file, 761*8c35d5eeSXin Li and even less who is responsible for the file at the moment. 762*8c35d5eeSXin Li 763*8c35d5eeSXin Li </p> 764*8c35d5eeSXin Li <p> 765*8c35d5eeSXin Li You should not include copyright information in individual source code files. 766*8c35d5eeSXin Li An exception is made for files meant to be disseminated as standalone. 767*8c35d5eeSXin Li </p> 768*8c35d5eeSXin Li 769*8c35d5eeSXin Li 770*8c35d5eeSXin Li </BODY> 771*8c35d5eeSXin Li </STYLEPOINT> 772*8c35d5eeSXin Li <STYLEPOINT title="Vertical white space"> 773*8c35d5eeSXin Li <SUMMARY> 774*8c35d5eeSXin Li Vertical white space: one blank line between top-level forms. 775*8c35d5eeSXin Li </SUMMARY> 776*8c35d5eeSXin Li <BODY> 777*8c35d5eeSXin Li <p> 778*8c35d5eeSXin Li You should include one blank line between top-level forms, 779*8c35d5eeSXin Li such as function definitions. 780*8c35d5eeSXin Li Exceptionally, blank lines can be omitted 781*8c35d5eeSXin Li between simple, closely related defining forms of the same kind, 782*8c35d5eeSXin Li such as a group of related type declarations or constant definitions. 783*8c35d5eeSXin Li </p> 784*8c35d5eeSXin Li <CODE_SNIPPET> 785*8c35d5eeSXin Li (defconstant +mix32+ #x12b9b0a1 "pi, an arbitrary number") 786*8c35d5eeSXin Li (defconstant +mix64+ #x2b992ddfa23249d6 "more digits of pi") 787*8c35d5eeSXin Li 788*8c35d5eeSXin Li (defconstant +golden-ratio32+ #x9e3779b9 "the golden ratio") 789*8c35d5eeSXin Li (defconstant +golden-ratio64+ #xe08c1d668b756f82 "more digits of the golden ratio") 790*8c35d5eeSXin Li 791*8c35d5eeSXin Li (defmacro incf32 (x y) 792*8c35d5eeSXin Li "Like INCF, but for integers modulo 2**32" 793*8c35d5eeSXin Li `(setf ,x (logand (+ ,x ,y) #xffffffff))) 794*8c35d5eeSXin Li (defmacro incf64 (x y) 795*8c35d5eeSXin Li "Like INCF, but for integers modulo 2**64" 796*8c35d5eeSXin Li `(setf ,x (logand (+ ,x ,y) #xffffffffffffffff))) 797*8c35d5eeSXin Li </CODE_SNIPPET> 798*8c35d5eeSXin Li <p> 799*8c35d5eeSXin Li Blank lines can be used to separate parts of a complicated function. 800*8c35d5eeSXin Li Generally, however, you should break a large function into smaller ones 801*8c35d5eeSXin Li instead of trying to make it more readable by adding vertical space. 802*8c35d5eeSXin Li If you can't, you should document with a <code>;;</code> comment 803*8c35d5eeSXin Li what each of the separated parts of the function does. 804*8c35d5eeSXin Li </p> 805*8c35d5eeSXin Li <p> 806*8c35d5eeSXin Li You should strive to keep top-level forms, 807*8c35d5eeSXin Li including comments but excluding the documentation string, of 808*8c35d5eeSXin Li appropriate length; preferrably short. Forms extending beyond a 809*8c35d5eeSXin Li single page should be rare and their use should be justfied. 810*8c35d5eeSXin Li This applies to each of the forms in an <code>eval-when</code>, 811*8c35d5eeSXin Li rather than to the <code>eval-when</code> itself. 812*8c35d5eeSXin Li Additionally, <code>defpackage</code> forms may be longer, 813*8c35d5eeSXin Li since they may include long lists of symbols. 814*8c35d5eeSXin Li </p> 815*8c35d5eeSXin Li </BODY> 816*8c35d5eeSXin Li </STYLEPOINT> 817*8c35d5eeSXin Li <STYLEPOINT title="Horizontal white space"> 818*8c35d5eeSXin Li <SUMMARY> 819*8c35d5eeSXin Li Horizontal white space: none around parentheses. No tabs. 820*8c35d5eeSXin Li </SUMMARY> 821*8c35d5eeSXin Li <BODY> 822*8c35d5eeSXin Li <p> 823*8c35d5eeSXin Li You must not include extra horizontal whitespace 824*8c35d5eeSXin Li before or after parentheses or around symbols. 825*8c35d5eeSXin Li </p> 826*8c35d5eeSXin Li <p> 827*8c35d5eeSXin Li You must not place right parentheses by themselves on a line. 828*8c35d5eeSXin Li A set of consecutive trailing parentheses must appear on the same line. 829*8c35d5eeSXin Li </p> 830*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 831*8c35d5eeSXin Li ;; Very Bad 832*8c35d5eeSXin Li ( defun factorial ( limit ) 833*8c35d5eeSXin Li ( let (( product 1 )) 834*8c35d5eeSXin Li ( loop for i from 1 upto limit 835*8c35d5eeSXin Li do (setf product ( * product i ) ) ) 836*8c35d5eeSXin Li product 837*8c35d5eeSXin Li ) 838*8c35d5eeSXin Li ) 839*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 840*8c35d5eeSXin Li <CODE_SNIPPET> 841*8c35d5eeSXin Li ;; Better 842*8c35d5eeSXin Li (defun factorial (limit) 843*8c35d5eeSXin Li (let ((product 1)) 844*8c35d5eeSXin Li (loop for i from 1 upto limit 845*8c35d5eeSXin Li do (setf product (* product i))) 846*8c35d5eeSXin Li product)) 847*8c35d5eeSXin Li </CODE_SNIPPET> 848*8c35d5eeSXin Li <p> 849*8c35d5eeSXin Li You should use only one space between forms. 850*8c35d5eeSXin Li </p> 851*8c35d5eeSXin Li <p> 852*8c35d5eeSXin Li You should not use spaces to vertically align forms 853*8c35d5eeSXin Li in the middle of consecutive lines. 854*8c35d5eeSXin Li An exception is made when the code possesses 855*8c35d5eeSXin Li an important yet otherwise not visible symmetry 856*8c35d5eeSXin Li that you want to emphasize. 857*8c35d5eeSXin Li </p> 858*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 859*8c35d5eeSXin Li ;; Bad 860*8c35d5eeSXin Li (let* ((low 1) 861*8c35d5eeSXin Li (high 2) 862*8c35d5eeSXin Li (sum (+ (* low low) (* high high)))) 863*8c35d5eeSXin Li ...) 864*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 865*8c35d5eeSXin Li <CODE_SNIPPET> 866*8c35d5eeSXin Li ;; Better 867*8c35d5eeSXin Li (let* ((low 1) 868*8c35d5eeSXin Li (high 2) 869*8c35d5eeSXin Li (sum (+ (* low low) (* high high)))) 870*8c35d5eeSXin Li ...)) 871*8c35d5eeSXin Li </CODE_SNIPPET> 872*8c35d5eeSXin Li <p> 873*8c35d5eeSXin Li You must align nested forms if they occur across more than one line. 874*8c35d5eeSXin Li </p> 875*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 876*8c35d5eeSXin Li ;; Bad 877*8c35d5eeSXin Li (defun munge (a b c) 878*8c35d5eeSXin Li (* (+ a b) 879*8c35d5eeSXin Li c)) 880*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 881*8c35d5eeSXin Li <CODE_SNIPPET> 882*8c35d5eeSXin Li ;; Better 883*8c35d5eeSXin Li (defun munge (a b c) 884*8c35d5eeSXin Li (* (+ a b) 885*8c35d5eeSXin Li c)) 886*8c35d5eeSXin Li </CODE_SNIPPET> 887*8c35d5eeSXin Li <p> 888*8c35d5eeSXin Li The convention is that the body of a binding form 889*8c35d5eeSXin Li is indented two spaces after the form. 890*8c35d5eeSXin Li Any binding data before the body is usually indented four spaces. 891*8c35d5eeSXin Li Arguments to a function call are aligned with the first argument; 892*8c35d5eeSXin Li if the first argument is on its own line, 893*8c35d5eeSXin Li it is aligned with the function name. 894*8c35d5eeSXin Li </p> 895*8c35d5eeSXin Li <CODE_SNIPPET> 896*8c35d5eeSXin Li (multiple-value-bind (a b c d) 897*8c35d5eeSXin Li (function-returning-four-values x y) 898*8c35d5eeSXin Li (declare (ignore c)) 899*8c35d5eeSXin Li (something-using a) 900*8c35d5eeSXin Li (also-using b d)) 901*8c35d5eeSXin Li </CODE_SNIPPET> 902*8c35d5eeSXin Li <p> 903*8c35d5eeSXin Li An exception to the rule against lonely parentheses 904*8c35d5eeSXin Li is made for an <code>eval-when</code> form around several definitions; 905*8c35d5eeSXin Li in this case, include a comment <code>; eval-when</code> 906*8c35d5eeSXin Li after the closing parenthesis. 907*8c35d5eeSXin Li </p> 908*8c35d5eeSXin Li <p> 909*8c35d5eeSXin Li You must set your editor to 910*8c35d5eeSXin Li avoid inserting tab characters in the files you edit. 911*8c35d5eeSXin Li Tabs cause confusion when editors disagree 912*8c35d5eeSXin Li on how many spaces they represent. 913*8c35d5eeSXin Li In Emacs, do <code>(setq-default indent-tabs-mode nil)</code>. 914*8c35d5eeSXin Li </p> 915*8c35d5eeSXin Li </BODY> 916*8c35d5eeSXin Li </STYLEPOINT> 917*8c35d5eeSXin Li</CATEGORY> 918*8c35d5eeSXin Li 919*8c35d5eeSXin Li<CATEGORY title="Documentation"> 920*8c35d5eeSXin Li <STYLEPOINT title="Document everything"> 921*8c35d5eeSXin Li <SUMMARY> 922*8c35d5eeSXin Li You should use document strings on all visible functions 923*8c35d5eeSXin Li to explain how to use your code. 924*8c35d5eeSXin Li </SUMMARY> 925*8c35d5eeSXin Li <BODY> 926*8c35d5eeSXin Li <p> 927*8c35d5eeSXin Li Unless some bit of code is painfully self-explanatory, 928*8c35d5eeSXin Li document it with a documentation string (also known as docstring). 929*8c35d5eeSXin Li </p> 930*8c35d5eeSXin Li <p> 931*8c35d5eeSXin Li Documentation strings are destined to be read 932*8c35d5eeSXin Li by the programmers who use your code. 933*8c35d5eeSXin Li They can be extracted from functions, types, classes, variables and macros, 934*8c35d5eeSXin Li and displayed by programming tools, such as IDEs, 935*8c35d5eeSXin Li or by REPL queries such as <code>(describe 'foo)</code>; 936*8c35d5eeSXin Li web-based documentation or other reference works 937*8c35d5eeSXin Li can be created based on them. 938*8c35d5eeSXin Li Documentation strings are thus the perfect locus to document your API. 939*8c35d5eeSXin Li They should describe how to use the code 940*8c35d5eeSXin Li (including what pitfalls to avoid), 941*8c35d5eeSXin Li as opposed to how the code works (and where more work is needed), 942*8c35d5eeSXin Li which is what you'll put in comments. 943*8c35d5eeSXin Li </p> 944*8c35d5eeSXin Li <p> 945*8c35d5eeSXin Li Supply a documentation string when defining 946*8c35d5eeSXin Li top-level functions, types, classes, variables and macros. 947*8c35d5eeSXin Li Generally, add a documentation string wherever the language allows. 948*8c35d5eeSXin Li </p> 949*8c35d5eeSXin Li <p> 950*8c35d5eeSXin Li For functions, the docstring should describe the function's contract: 951*8c35d5eeSXin Li what the function does, 952*8c35d5eeSXin Li what the arguments mean, 953*8c35d5eeSXin Li what values are returned, 954*8c35d5eeSXin Li what conditions the function can signal. 955*8c35d5eeSXin Li It should be expressed at the appropriate level of abstraction, 956*8c35d5eeSXin Li explaining the intended meaning rather than, say, just the syntax. 957*8c35d5eeSXin Li In documentation strings, capitalize the names of Lisp symbols, 958*8c35d5eeSXin Li such as function arguments. 959*8c35d5eeSXin Li For example, "The value of LENGTH should be an integer." 960*8c35d5eeSXin Li </p> 961*8c35d5eeSXin Li <CODE_SNIPPET> 962*8c35d5eeSXin Li (defun small-prime-number-p (n) 963*8c35d5eeSXin Li "Return T if N, an integer, is a prime number. Otherwise, return NIL." 964*8c35d5eeSXin Li (cond ((or (< n 2)) 965*8c35d5eeSXin Li nil) 966*8c35d5eeSXin Li ((= n 2) 967*8c35d5eeSXin Li t) 968*8c35d5eeSXin Li ((divisorp 2 n) 969*8c35d5eeSXin Li nil) 970*8c35d5eeSXin Li (t 971*8c35d5eeSXin Li (loop for i from 3 upto (sqrt n) by 2 972*8c35d5eeSXin Li never (divisorp i n))))) 973*8c35d5eeSXin Li </CODE_SNIPPET> 974*8c35d5eeSXin Li <CODE_SNIPPET> 975*8c35d5eeSXin Li (defgeneric table-clear (table) 976*8c35d5eeSXin Li (:documentation 977*8c35d5eeSXin Li "Like clrhash, empties the TABLE of all 978*8c35d5eeSXin Li associations, and returns the table itself.")) 979*8c35d5eeSXin Li </CODE_SNIPPET> 980*8c35d5eeSXin Li <p> 981*8c35d5eeSXin Li A long docstring may usefully 982*8c35d5eeSXin Li begin with a short, single-sentence summary, 983*8c35d5eeSXin Li followed by the larger body of the docstring. 984*8c35d5eeSXin Li </p> 985*8c35d5eeSXin Li <p> 986*8c35d5eeSXin Li When the name of a type is used, 987*8c35d5eeSXin Li the symbol may be quoted by surrounding it with 988*8c35d5eeSXin Li a back quote at the beginning and a single quote at the end. 989*8c35d5eeSXin Li Emacs will highlight the type, and the highlighting serves 990*8c35d5eeSXin Li as a cue to the reader that <kbd>M-.</kbd> 991*8c35d5eeSXin Li will lead to the symbol's definition. 992*8c35d5eeSXin Li </p> 993*8c35d5eeSXin Li <CODE_SNIPPET> 994*8c35d5eeSXin Li (defun bag-tag-expected-itinerary (bag-tag) 995*8c35d5eeSXin Li "Return a list of `legacy-pnr-pax-segment' objects representing 996*8c35d5eeSXin Li the expected itinerary of the `bag-tag' object, BAG-TAG." 997*8c35d5eeSXin Li ...) 998*8c35d5eeSXin Li </CODE_SNIPPET> 999*8c35d5eeSXin Li <p> 1000*8c35d5eeSXin Li Every method of a generic function should be independently documented 1001*8c35d5eeSXin Li when the specialization affects what the method does, 1002*8c35d5eeSXin Li beyond what is described in its generic function's docstring. 1003*8c35d5eeSXin Li </p> 1004*8c35d5eeSXin Li <p> 1005*8c35d5eeSXin Li When you fix a bug, 1006*8c35d5eeSXin Li consider whether what the fixed code does is obviously correct or not; 1007*8c35d5eeSXin Li if not, you must add a comment explaining 1008*8c35d5eeSXin Li the reason for the code in terms of fixing the bug. 1009*8c35d5eeSXin Li Adding the bug number, if any, is also recommended. 1010*8c35d5eeSXin Li </p> 1011*8c35d5eeSXin Li </BODY> 1012*8c35d5eeSXin Li </STYLEPOINT> 1013*8c35d5eeSXin Li <STYLEPOINT title="Comment semicolons"> 1014*8c35d5eeSXin Li <SUMMARY> 1015*8c35d5eeSXin Li You must use the appropriate number of semicolons to introduce comments. 1016*8c35d5eeSXin Li </SUMMARY> 1017*8c35d5eeSXin Li <BODY> 1018*8c35d5eeSXin Li <p> 1019*8c35d5eeSXin Li Comments are explanations to the future maintainers of the code. 1020*8c35d5eeSXin Li Even if you're the only person who will ever see and touch the code, 1021*8c35d5eeSXin Li even if you're either immortal and never going to quit, 1022*8c35d5eeSXin Li or unconcerned with what happens after you leave 1023*8c35d5eeSXin Li (and have your code self-destruct in such an eventuality), 1024*8c35d5eeSXin Li you may find it useful to comment your code. 1025*8c35d5eeSXin Li Indeed, by the time you revisit your code, 1026*8c35d5eeSXin Li weeks, months or years later, 1027*8c35d5eeSXin Li you will find yourself a different person from the one who wrote it, 1028*8c35d5eeSXin Li and you will be grateful to that previous self 1029*8c35d5eeSXin Li for making the code readable. 1030*8c35d5eeSXin Li </p> 1031*8c35d5eeSXin Li <p> 1032*8c35d5eeSXin Li You must comment anything complicated 1033*8c35d5eeSXin Li so that the next developer can understand what's going on. 1034*8c35d5eeSXin Li (Again, the "hit by a truck" principle.) 1035*8c35d5eeSXin Li </p> 1036*8c35d5eeSXin Li <p> 1037*8c35d5eeSXin Li Also use comments as a way to guide those who read the code, 1038*8c35d5eeSXin Li so they know what to find where. 1039*8c35d5eeSXin Li </p> 1040*8c35d5eeSXin Li <ul> 1041*8c35d5eeSXin Li <li> 1042*8c35d5eeSXin Li File headers and important comments 1043*8c35d5eeSXin Li that apply to large sections of code in a source file 1044*8c35d5eeSXin Li should begin with four semicolons. 1045*8c35d5eeSXin Li </li> 1046*8c35d5eeSXin Li <li> 1047*8c35d5eeSXin Li You should use three semicolons 1048*8c35d5eeSXin Li to begin comments that apply to just 1049*8c35d5eeSXin Li one top-level form or small group of top-level forms. 1050*8c35d5eeSXin Li </li> 1051*8c35d5eeSXin Li <li> 1052*8c35d5eeSXin Li Inside a top-level form, you should use two semicolons 1053*8c35d5eeSXin Li to begin a comment if it appears between lines. 1054*8c35d5eeSXin Li </li> 1055*8c35d5eeSXin Li <li> 1056*8c35d5eeSXin Li You should use one semicolon if it is a parenthetical remark 1057*8c35d5eeSXin Li and occurs at the end of a line. 1058*8c35d5eeSXin Li You should use spaces to separate the comment 1059*8c35d5eeSXin Li from the code it refers to so the comment stands out. 1060*8c35d5eeSXin Li You should try to vertically align 1061*8c35d5eeSXin Li consecutive related end-of-line comments. 1062*8c35d5eeSXin Li </li> 1063*8c35d5eeSXin Li </ul> 1064*8c35d5eeSXin Li <CODE_SNIPPET> 1065*8c35d5eeSXin Li ;;;; project-euler.lisp 1066*8c35d5eeSXin Li ;;;; File-level comments or comments for large sections of code. 1067*8c35d5eeSXin Li 1068*8c35d5eeSXin Li ;;; Problems are described in more detail here: https://projecteuler.net/ 1069*8c35d5eeSXin Li 1070*8c35d5eeSXin Li ;;; Divisibility 1071*8c35d5eeSXin Li ;;; Comments that describe a group of definitions. 1072*8c35d5eeSXin Li 1073*8c35d5eeSXin Li (defun divisorp (d n) 1074*8c35d5eeSXin Li (zerop (mod n d))) 1075*8c35d5eeSXin Li 1076*8c35d5eeSXin Li (defun proper-divisors (n) 1077*8c35d5eeSXin Li ...) 1078*8c35d5eeSXin Li 1079*8c35d5eeSXin Li (defun divisors (n) 1080*8c35d5eeSXin Li (cons n (proper-divisors n))) 1081*8c35d5eeSXin Li 1082*8c35d5eeSXin Li ;;; Prime numbers 1083*8c35d5eeSXin Li 1084*8c35d5eeSXin Li (defun small-prime-number-p (n) 1085*8c35d5eeSXin Li (cond ((or (< n 2)) 1086*8c35d5eeSXin Li nil) 1087*8c35d5eeSXin Li ((= n 2) ; parenthetical remark here 1088*8c35d5eeSXin Li t) ; continuation of the remark 1089*8c35d5eeSXin Li ((divisorp 2 n) 1090*8c35d5eeSXin Li nil) ; different remark 1091*8c35d5eeSXin Li ;; Comment that applies to a section of code. 1092*8c35d5eeSXin Li (t 1093*8c35d5eeSXin Li (loop for i from 3 upto (sqrt n) by 2 1094*8c35d5eeSXin Li never (divisorp i n))))) 1095*8c35d5eeSXin Li </CODE_SNIPPET> 1096*8c35d5eeSXin Li <p> 1097*8c35d5eeSXin Li You should include a space between the semicolon and the text of the comment. 1098*8c35d5eeSXin Li </p> 1099*8c35d5eeSXin Li </BODY> 1100*8c35d5eeSXin Li </STYLEPOINT> 1101*8c35d5eeSXin Li <STYLEPOINT title="Grammar and punctuation"> 1102*8c35d5eeSXin Li <SUMMARY> 1103*8c35d5eeSXin Li You should punctuate documentation correctly. 1104*8c35d5eeSXin Li </SUMMARY> 1105*8c35d5eeSXin Li <BODY> 1106*8c35d5eeSXin Li <p> 1107*8c35d5eeSXin Li When a comment is a full sentence, 1108*8c35d5eeSXin Li you should capitalize the initial letter of the first word 1109*8c35d5eeSXin Li and end the comment with a period. 1110*8c35d5eeSXin Li In general, you should use correct punctuation. 1111*8c35d5eeSXin Li </p> 1112*8c35d5eeSXin Li </BODY> 1113*8c35d5eeSXin Li </STYLEPOINT> 1114*8c35d5eeSXin Li <STYLEPOINT title="Attention Required"> 1115*8c35d5eeSXin Li <SUMMARY> 1116*8c35d5eeSXin Li You must follow the convention of using TODO comments 1117*8c35d5eeSXin Li for code requiring special attention. 1118*8c35d5eeSXin Li For code using unobvious forms, you must include a comment. 1119*8c35d5eeSXin Li </SUMMARY> 1120*8c35d5eeSXin Li <BODY> 1121*8c35d5eeSXin Li <p> 1122*8c35d5eeSXin Li For comments requiring special attention, such as 1123*8c35d5eeSXin Li incomplete code, todo items, questions, breakage, and danger, 1124*8c35d5eeSXin Li include a TODO comment indicating the type of problem, 1125*8c35d5eeSXin Li its nature, and any notes on how it may be addressed. 1126*8c35d5eeSXin Li </p> 1127*8c35d5eeSXin Li <p> 1128*8c35d5eeSXin Li The comments begin with <code>TODO</code> in all capital letters, 1129*8c35d5eeSXin Li followed by the 1130*8c35d5eeSXin Li 1131*8c35d5eeSXin Li name, e-mail address, or other identifier 1132*8c35d5eeSXin Li of the person 1133*8c35d5eeSXin Li with the best context about the problem referenced by the <code>TODO</code>. 1134*8c35d5eeSXin Li The main purpose is to have a consistent <code>TODO</code> that 1135*8c35d5eeSXin Li can be searched to find out how to get more details upon 1136*8c35d5eeSXin Li request. A <code>TODO</code> is not a commitment that the 1137*8c35d5eeSXin Li person referenced will fix the problem. Thus when you create 1138*8c35d5eeSXin Li a <code>TODO</code>, 1139*8c35d5eeSXin Li it is almost always your 1140*8c35d5eeSXin Li name 1141*8c35d5eeSXin Li that is given. 1142*8c35d5eeSXin Li </p> 1143*8c35d5eeSXin Li <p> 1144*8c35d5eeSXin Li When signing comments, 1145*8c35d5eeSXin Li you should use your username (for code within the company) 1146*8c35d5eeSXin Li or full email address (for code visible outside the company), 1147*8c35d5eeSXin Li not just initials. 1148*8c35d5eeSXin Li 1149*8c35d5eeSXin Li </p> 1150*8c35d5eeSXin Li <CODE_SNIPPET> 1151*8c35d5eeSXin Li ;;--- TODO([email protected]): Refactor to provide a better API. 1152*8c35d5eeSXin Li </CODE_SNIPPET> 1153*8c35d5eeSXin Li <p> 1154*8c35d5eeSXin Li Be specific when indicating times or software releases 1155*8c35d5eeSXin Li in a TODO comment and use 1156*8c35d5eeSXin Li <a HREF="https://www.w3.org/TR/NOTE-datetime">YYYY-MM-DD</a> 1157*8c35d5eeSXin Li format for dates to make automated processing of such dates easier, 1158*8c35d5eeSXin Li e.g., 2038-01-20 for the end of the 32-bit signed <code>time_t</code>. 1159*8c35d5eeSXin Li </p> 1160*8c35d5eeSXin Li <CODE_SNIPPET> 1161*8c35d5eeSXin Li ;;--- TODO(brown): Remove this code after release 1.7 or before 2012-11-30. 1162*8c35d5eeSXin Li </CODE_SNIPPET> 1163*8c35d5eeSXin Li <p> 1164*8c35d5eeSXin Li For code that uses unobvious forms to accomplish a task, you must include a comment 1165*8c35d5eeSXin Li stating the purpose of the form and the task it accomplishes. 1166*8c35d5eeSXin Li </p> 1167*8c35d5eeSXin Li </BODY> 1168*8c35d5eeSXin Li </STYLEPOINT> 1169*8c35d5eeSXin Li <STYLEPOINT title="Domain-Specific Languages"> 1170*8c35d5eeSXin Li <SUMMARY> 1171*8c35d5eeSXin Li You should document DSLs and 1172*8c35d5eeSXin Li any terse program in a DSL. 1173*8c35d5eeSXin Li </SUMMARY> 1174*8c35d5eeSXin Li <BODY> 1175*8c35d5eeSXin Li <p> 1176*8c35d5eeSXin Li You should design your Domain Specific Language 1177*8c35d5eeSXin Li to be easy to read and understand by people familiar with the domain. 1178*8c35d5eeSXin Li </p> 1179*8c35d5eeSXin Li <p> 1180*8c35d5eeSXin Li You must properly document all your Domain Specific Language. 1181*8c35d5eeSXin Li </p> 1182*8c35d5eeSXin Li <p> 1183*8c35d5eeSXin Li Sometimes, your DSL is designed for terseness. 1184*8c35d5eeSXin Li In that case, it is important to document what each program does, 1185*8c35d5eeSXin Li if it's not painfully obvious from the context. 1186*8c35d5eeSXin Li </p> 1187*8c35d5eeSXin Li <p> 1188*8c35d5eeSXin Li Notably, when you use regular expressions 1189*8c35d5eeSXin Li (e.g. with the <code>CL-PPCRE</code> package), 1190*8c35d5eeSXin Li you MUST ALWAYS put in a comment 1191*8c35d5eeSXin Li (usually a two-semicolon comment on the previous line) 1192*8c35d5eeSXin Li explaining, at least basically, what the regular expression does, 1193*8c35d5eeSXin Li or what the purpose of using it is. 1194*8c35d5eeSXin Li The comment need not spell out every bit of the syntax, but 1195*8c35d5eeSXin Li it should be possible for someone to follow the logic of the code 1196*8c35d5eeSXin Li without actually parsing the regular expression. 1197*8c35d5eeSXin Li </p> 1198*8c35d5eeSXin Li </BODY> 1199*8c35d5eeSXin Li </STYLEPOINT> 1200*8c35d5eeSXin Li 1201*8c35d5eeSXin Li</CATEGORY> 1202*8c35d5eeSXin Li 1203*8c35d5eeSXin Li<CATEGORY title="Naming"> 1204*8c35d5eeSXin Li <STYLEPOINT title="Symbol guidelines"> 1205*8c35d5eeSXin Li <SUMMARY> 1206*8c35d5eeSXin Li You should use lower case. 1207*8c35d5eeSXin Li You should follow the rules for <a href="#Spelling_and_Abbreviations">Spelling and Abbreviations</a> 1208*8c35d5eeSXin Li You should follow punctuation conventions. 1209*8c35d5eeSXin Li </SUMMARY> 1210*8c35d5eeSXin Li <BODY> 1211*8c35d5eeSXin Li <p> 1212*8c35d5eeSXin Li Use lower case for all symbols. 1213*8c35d5eeSXin Li Consistently using lower case makes searching for symbol names easier 1214*8c35d5eeSXin Li and is more readable. 1215*8c35d5eeSXin Li </p> 1216*8c35d5eeSXin Li <p> 1217*8c35d5eeSXin Li Note that Common Lisp is case-converting, 1218*8c35d5eeSXin Li and that the <code>symbol-name</code> of your symbols 1219*8c35d5eeSXin Li will be upper case. 1220*8c35d5eeSXin Li Because of this case-converting, 1221*8c35d5eeSXin Li attempts to distinguish symbols by case are defeated, 1222*8c35d5eeSXin Li and only result in confusion. 1223*8c35d5eeSXin Li While it is possible to escape characters in symbols 1224*8c35d5eeSXin Li to force lower case, 1225*8c35d5eeSXin Li you should not use this capability 1226*8c35d5eeSXin Li unless this is somehow necessary 1227*8c35d5eeSXin Li to interoperate with third-party software. 1228*8c35d5eeSXin Li </p> 1229*8c35d5eeSXin Li <p> 1230*8c35d5eeSXin Li Place hyphens between all the words in a symbol. 1231*8c35d5eeSXin Li If you can't easily say an identifier out loud, 1232*8c35d5eeSXin Li it is probably badly named. 1233*8c35d5eeSXin Li </p> 1234*8c35d5eeSXin Li <p> 1235*8c35d5eeSXin Li You must not use <code>"/"</code> or <code>"."</code> 1236*8c35d5eeSXin Li instead of <code>"-"</code> 1237*8c35d5eeSXin Li unless you have a well-documented overarching reason to, 1238*8c35d5eeSXin Li and permission from other hackers who review your proposal. 1239*8c35d5eeSXin Li </p> 1240*8c35d5eeSXin Li <p> 1241*8c35d5eeSXin Li See the section on <a href="#Spelling_and_Abbreviations">Spelling and Abbreviations</a> 1242*8c35d5eeSXin Li for guidelines on using abbreviations. 1243*8c35d5eeSXin Li </p> 1244*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 1245*8c35d5eeSXin Li ;; Bad 1246*8c35d5eeSXin Li (defvar *default-username* "Ann") 1247*8c35d5eeSXin Li (defvar *max-widget-cnt* 200) 1248*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 1249*8c35d5eeSXin Li <CODE_SNIPPET> 1250*8c35d5eeSXin Li ;; Better 1251*8c35d5eeSXin Li (defvar *default-user-name* "Ann") 1252*8c35d5eeSXin Li (defvar *maximum-widget-count* 200) 1253*8c35d5eeSXin Li </CODE_SNIPPET> 1254*8c35d5eeSXin Li <p> 1255*8c35d5eeSXin Li There are conventions in Common Lisp 1256*8c35d5eeSXin Li for the use of punctuation in symbols. 1257*8c35d5eeSXin Li You should not use punctuation in symbols outside these conventions. 1258*8c35d5eeSXin Li </p> 1259*8c35d5eeSXin Li <p> 1260*8c35d5eeSXin Li Unless the scope of a variable is very small, 1261*8c35d5eeSXin Li do not use overly short names like 1262*8c35d5eeSXin Li <code>i</code> and <code>zq</code>. 1263*8c35d5eeSXin Li </p> 1264*8c35d5eeSXin Li </BODY> 1265*8c35d5eeSXin Li </STYLEPOINT> 1266*8c35d5eeSXin Li <STYLEPOINT title="Denote intent, not content"> 1267*8c35d5eeSXin Li <SUMMARY> 1268*8c35d5eeSXin Li Name your variables according to their intent, 1269*8c35d5eeSXin Li not their content. 1270*8c35d5eeSXin Li </SUMMARY> 1271*8c35d5eeSXin Li <BODY> 1272*8c35d5eeSXin Li <p> 1273*8c35d5eeSXin Li You should name a variable according 1274*8c35d5eeSXin Li to the high-level concept that it represents, 1275*8c35d5eeSXin Li not according to the low-level implementation details 1276*8c35d5eeSXin Li of how the concept is represented. 1277*8c35d5eeSXin Li </p> 1278*8c35d5eeSXin Li <p> 1279*8c35d5eeSXin Li Thus, you should avoid embedding 1280*8c35d5eeSXin Li data structure or aggregate type names, 1281*8c35d5eeSXin Li such as <code>list</code>, <code>array</code>, or 1282*8c35d5eeSXin Li <code>hash-table</code> inside variable names, 1283*8c35d5eeSXin Li unless you're writing a generic algorithm that applies to 1284*8c35d5eeSXin Li arbitrary lists, arrays, hash-tables, etc. 1285*8c35d5eeSXin Li In that case it's perfectly OK to name a variable 1286*8c35d5eeSXin Li <code>list</code> or <code>array</code>. 1287*8c35d5eeSXin Li </p> 1288*8c35d5eeSXin Li <p> 1289*8c35d5eeSXin Li Indeed, you should be introducing new abstract data types 1290*8c35d5eeSXin Li with <code>DEFCLASS</code> or <code>DEFTYPE</code>, 1291*8c35d5eeSXin Li whenever a new kind of intent appears for objects in your protocols. 1292*8c35d5eeSXin Li Functions that manipulate such objects generically may then 1293*8c35d5eeSXin Li use variables the name of which reflect that abstract type. 1294*8c35d5eeSXin Li </p> 1295*8c35d5eeSXin Li <p> 1296*8c35d5eeSXin Li For example, if a variable's value is always a row 1297*8c35d5eeSXin Li (or is either a row or <code>NIL</code>), 1298*8c35d5eeSXin Li it's good to call it <code>row</code> or <code>first-row</code> 1299*8c35d5eeSXin Li or something like that. 1300*8c35d5eeSXin Li It is alright is <code>row</code> has been 1301*8c35d5eeSXin Li <code>DEFTYPE</code>'d to <code>STRING</code> — 1302*8c35d5eeSXin Li precisely because you have abstracted the detail away, 1303*8c35d5eeSXin Li and the remaining salient point is that it is a row. 1304*8c35d5eeSXin Li You should not name the variable <code>STRING</code> in this context, 1305*8c35d5eeSXin Li except possibly in low-level functions that specifically manipulate 1306*8c35d5eeSXin Li the innards of rows to provide the suitable abstraction. 1307*8c35d5eeSXin Li </p> 1308*8c35d5eeSXin Li <p> 1309*8c35d5eeSXin Li Be consistent. 1310*8c35d5eeSXin Li If a variable is named <code>row</code> in one function, 1311*8c35d5eeSXin Li and its value is being passed to a second function, 1312*8c35d5eeSXin Li then call it <code>row</code> rather than, say, <code>value</code> 1313*8c35d5eeSXin Li (this was a real case). 1314*8c35d5eeSXin Li </p> 1315*8c35d5eeSXin Li </BODY> 1316*8c35d5eeSXin Li </STYLEPOINT> 1317*8c35d5eeSXin Li <STYLEPOINT title="Global variables and constants"> 1318*8c35d5eeSXin Li <SUMMARY> 1319*8c35d5eeSXin Li Name globals according to convention. 1320*8c35d5eeSXin Li </SUMMARY> 1321*8c35d5eeSXin Li <BODY> 1322*8c35d5eeSXin Li <p> 1323*8c35d5eeSXin Li The names of global constants should start and end 1324*8c35d5eeSXin Li with plus characters. 1325*8c35d5eeSXin Li </p> 1326*8c35d5eeSXin Li <p> 1327*8c35d5eeSXin Li Global variable names should start and end with asterisks 1328*8c35d5eeSXin Li (also known in this context as earmuffs). 1329*8c35d5eeSXin Li </p> 1330*8c35d5eeSXin Li <p> 1331*8c35d5eeSXin Li In some projects, parameters that are not meant 1332*8c35d5eeSXin Li to be usually modified or bound under normal circumstances 1333*8c35d5eeSXin Li (but may be during experimentation or exceptional situations) 1334*8c35d5eeSXin Li should start (but do not end) with a dollar sign. 1335*8c35d5eeSXin Li If such a convention exists within your project, 1336*8c35d5eeSXin Li you should follow it consistently. 1337*8c35d5eeSXin Li Otherwise, you should avoid naming variables like this. 1338*8c35d5eeSXin Li </p> 1339*8c35d5eeSXin Li <p> 1340*8c35d5eeSXin Li Common Lisp does not have global lexical variables, 1341*8c35d5eeSXin Li so a naming convention is used to ensure that globals, 1342*8c35d5eeSXin Li which are dynamically bound, 1343*8c35d5eeSXin Li never have names that overlap with local variables. 1344*8c35d5eeSXin Li It is possible to fake global lexical variables 1345*8c35d5eeSXin Li with a differently named global variable 1346*8c35d5eeSXin Li and a <code>DEFINE-SYMBOL-MACRO</code>. 1347*8c35d5eeSXin Li You should not use this trick, 1348*8c35d5eeSXin Li unless you first publish a library that abstracts it away. 1349*8c35d5eeSXin Li </p> 1350*8c35d5eeSXin Li <CODE_SNIPPET> 1351*8c35d5eeSXin Li (defconstant +hash-results+ #xbd49d10d10cbee50) 1352*8c35d5eeSXin Li 1353*8c35d5eeSXin Li (defvar *maximum-search-depth* 100) 1354*8c35d5eeSXin Li </CODE_SNIPPET> 1355*8c35d5eeSXin Li </BODY> 1356*8c35d5eeSXin Li </STYLEPOINT> 1357*8c35d5eeSXin Li <STYLEPOINT title="Predicate names"> 1358*8c35d5eeSXin Li <SUMMARY> 1359*8c35d5eeSXin Li Names of predicate functions and variables end with a <code>"P"</code>. 1360*8c35d5eeSXin Li </SUMMARY> 1361*8c35d5eeSXin Li <BODY> 1362*8c35d5eeSXin Li <p> 1363*8c35d5eeSXin Li You should name boolean-valued functions and variables with a 1364*8c35d5eeSXin Li trailing <code>"P"</code> or <code>"-P"</code>, 1365*8c35d5eeSXin Li to indicate they are predicates. 1366*8c35d5eeSXin Li Generally, you should use 1367*8c35d5eeSXin Li <code>"P"</code> when the rest of the function name is one word 1368*8c35d5eeSXin Li and <code>"-P"</code> when it is more than one word. 1369*8c35d5eeSXin Li </p> 1370*8c35d5eeSXin Li <p> 1371*8c35d5eeSXin Li A rationale for this convention is given in 1372*8c35d5eeSXin Li <a href="http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html">the CLtL2 chapter on predicates</a>. 1373*8c35d5eeSXin Li </p> 1374*8c35d5eeSXin Li <p> 1375*8c35d5eeSXin Li For uniformity, you should follow the convention above, 1376*8c35d5eeSXin Li and not one of the alternatives below. 1377*8c35d5eeSXin Li </p> 1378*8c35d5eeSXin Li <p> 1379*8c35d5eeSXin Li An alternative rule used in some existing packages 1380*8c35d5eeSXin Li is to always use <code>"-P"</code>. 1381*8c35d5eeSXin Li Another alternative rule used in some existing packages 1382*8c35d5eeSXin Li is to always use <code>"?"</code>. 1383*8c35d5eeSXin Li When you develop such a package, 1384*8c35d5eeSXin Li you must be consistent with the rest of the package. 1385*8c35d5eeSXin Li When you start a new package, 1386*8c35d5eeSXin Li you should not use such an alternative rule 1387*8c35d5eeSXin Li without a very good documented reason. 1388*8c35d5eeSXin Li </p> 1389*8c35d5eeSXin Li </BODY> 1390*8c35d5eeSXin Li </STYLEPOINT> 1391*8c35d5eeSXin Li <STYLEPOINT title="Omit library prefixes"> 1392*8c35d5eeSXin Li <SUMMARY> 1393*8c35d5eeSXin Li You should not include a library or package name 1394*8c35d5eeSXin Li as a prefix within the name of symbols. 1395*8c35d5eeSXin Li </SUMMARY> 1396*8c35d5eeSXin Li <BODY> 1397*8c35d5eeSXin Li <p> 1398*8c35d5eeSXin Li When naming a symbol (external or internal) in a package, 1399*8c35d5eeSXin Li you should not include the package name 1400*8c35d5eeSXin Li as a prefix within the name of the symbol. 1401*8c35d5eeSXin Li Naming a symbol this way makes it awkward to use 1402*8c35d5eeSXin Li from a client package accessing the symbol 1403*8c35d5eeSXin Li by qualifying it with a package prefix, 1404*8c35d5eeSXin Li where the package name then appears twice 1405*8c35d5eeSXin Li (once as a package prefix, 1406*8c35d5eeSXin Li another time as a prefix within the symbol name). 1407*8c35d5eeSXin Li </p> 1408*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 1409*8c35d5eeSXin Li ;; Bad 1410*8c35d5eeSXin Li (in-package #:varint) 1411*8c35d5eeSXin Li (defun varint-length64 () ... ) 1412*8c35d5eeSXin Li 1413*8c35d5eeSXin Li (in-package #:client-code) 1414*8c35d5eeSXin Li (defconst +padding+ (varint:varint-length64 +end-token+)) 1415*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 1416*8c35d5eeSXin Li <CODE_SNIPPET> 1417*8c35d5eeSXin Li ;; Better 1418*8c35d5eeSXin Li (in-package #:varint) 1419*8c35d5eeSXin Li (defun length64 () ... ) 1420*8c35d5eeSXin Li 1421*8c35d5eeSXin Li (in-package #:client-code) 1422*8c35d5eeSXin Li (defconst +padding+ (varint:length64 +end-token+)) 1423*8c35d5eeSXin Li </CODE_SNIPPET> 1424*8c35d5eeSXin Li <p> 1425*8c35d5eeSXin Li An exception to the above rule would be to include a prefix 1426*8c35d5eeSXin Li for the names of variables that would otherwise be expected to clash 1427*8c35d5eeSXin Li with variables in packages that use the current one. 1428*8c35d5eeSXin Li For instance, <code>ASDF</code> exports a variable <code>*ASDF-VERBOSE*</code> 1429*8c35d5eeSXin Li that controls the verbosity of <code>ASDF</code> only, 1430*8c35d5eeSXin Li rather than of the entire Lisp program. 1431*8c35d5eeSXin Li </p> 1432*8c35d5eeSXin Li </BODY> 1433*8c35d5eeSXin Li </STYLEPOINT> 1434*8c35d5eeSXin Li <STYLEPOINT title="Packages"> 1435*8c35d5eeSXin Li <SUMMARY> 1436*8c35d5eeSXin Li Use packages appropriately. 1437*8c35d5eeSXin Li </SUMMARY> 1438*8c35d5eeSXin Li <BODY> 1439*8c35d5eeSXin Li <p> 1440*8c35d5eeSXin Li Lisp packages are used to demarcate namespaces. 1441*8c35d5eeSXin Li Usually, each system has its own namespace. 1442*8c35d5eeSXin Li A package has a set of external symbols, 1443*8c35d5eeSXin Li which are intended to be used from outside the package, 1444*8c35d5eeSXin Li in order to allow other modules to use this module's facilities. 1445*8c35d5eeSXin Li </p> 1446*8c35d5eeSXin Li <p> 1447*8c35d5eeSXin Li The internal symbols of a package 1448*8c35d5eeSXin Li should never be referred to from other packages. 1449*8c35d5eeSXin Li That is, you should never have to use 1450*8c35d5eeSXin Li the double-colon <code>::</code> construct. 1451*8c35d5eeSXin Li (e.g. <code>QUAKE::HIDDEN-FUNCTION</code>). 1452*8c35d5eeSXin Li If you need to use double-colons to write real production code, 1453*8c35d5eeSXin Li something is wrong and needs to be fixed. 1454*8c35d5eeSXin Li </p> 1455*8c35d5eeSXin Li <p> 1456*8c35d5eeSXin Li As an exception, 1457*8c35d5eeSXin Li unit tests may use the internals of the package being tested. 1458*8c35d5eeSXin Li So when you refactor, watch out for 1459*8c35d5eeSXin Li internals used by the package's unit tests. 1460*8c35d5eeSXin Li </p> 1461*8c35d5eeSXin Li <p> 1462*8c35d5eeSXin Li The <code>::</code> construct is also useful for very temporary hacks, 1463*8c35d5eeSXin Li and at the REPL. 1464*8c35d5eeSXin Li But if the symbol really is part of 1465*8c35d5eeSXin Li the externally-visible definition of the package, 1466*8c35d5eeSXin Li export it. 1467*8c35d5eeSXin Li </p> 1468*8c35d5eeSXin Li <p> 1469*8c35d5eeSXin Li You may find that some internal symbols represent concepts 1470*8c35d5eeSXin Li you usually want to abstract away and hide under the hood, 1471*8c35d5eeSXin Li yet at times are necessary to expose for various extensions. 1472*8c35d5eeSXin Li For the former reason, you do not want to export them, 1473*8c35d5eeSXin Li yet for the latter reason, you have to export them. 1474*8c35d5eeSXin Li The solution is to have two different packages, 1475*8c35d5eeSXin Li one for your normal users to use, and 1476*8c35d5eeSXin Li another for the implementation and its extenders to use. 1477*8c35d5eeSXin Li </p> 1478*8c35d5eeSXin Li <p> 1479*8c35d5eeSXin Li Each package is one of two types: 1480*8c35d5eeSXin Li </p> 1481*8c35d5eeSXin Li <ul> 1482*8c35d5eeSXin Li <li> 1483*8c35d5eeSXin Li Intended to be included 1484*8c35d5eeSXin Li in the <code>:use</code> specification of other packages. 1485*8c35d5eeSXin Li If package <code>A</code> "uses" package <code>B</code>, 1486*8c35d5eeSXin Li then the external symbols of package <code>B</code> 1487*8c35d5eeSXin Li can be referenced from within package <code>A</code> 1488*8c35d5eeSXin Li without a package prefix. 1489*8c35d5eeSXin Li We mainly use this for low-level modules 1490*8c35d5eeSXin Li that provide widely-used facilities. 1491*8c35d5eeSXin Li </li> 1492*8c35d5eeSXin Li <li> 1493*8c35d5eeSXin Li Not intended to be "used". 1494*8c35d5eeSXin Li To reference a facility provided by package <code>B</code>, 1495*8c35d5eeSXin Li code in package <code>A</code> must use an explicit package prefix, 1496*8c35d5eeSXin Li e.g. <code>B:DO-THIS</code>. 1497*8c35d5eeSXin Li </li> 1498*8c35d5eeSXin Li </ul> 1499*8c35d5eeSXin Li <p> 1500*8c35d5eeSXin Li If you add a new package, it should always be of the second type, 1501*8c35d5eeSXin Li unless you have a special reason and get permission. 1502*8c35d5eeSXin Li Usually a package is designed to be one or the other, 1503*8c35d5eeSXin Li by virtue of the names of the functions. 1504*8c35d5eeSXin Li For example, if you have an abstraction called <code>FIFO</code>, 1505*8c35d5eeSXin Li and it were in a package of the first type 1506*8c35d5eeSXin Li you'd have functions named things like 1507*8c35d5eeSXin Li <code>FIFO-ADD-TO</code> and <code>FIFO-CLEAR-ALL</code>. 1508*8c35d5eeSXin Li If you used a package of the second type, 1509*8c35d5eeSXin Li you'd have names like <code>ADD-TO</code> and <code>CLEAR-ALL</code>, 1510*8c35d5eeSXin Li because the callers would be saying 1511*8c35d5eeSXin Li <code>FIFO:ADD-TO</code> and <code>FIFO:CLEAR-ALL</code>. 1512*8c35d5eeSXin Li (<code>FIFO:FIFO-CLEAR-ALL</code> is redundant and ugly.) 1513*8c35d5eeSXin Li </p> 1514*8c35d5eeSXin Li <p> 1515*8c35d5eeSXin Li Another good thing about packages is that 1516*8c35d5eeSXin Li your symbol names won't "collide" with the names of other packages, 1517*8c35d5eeSXin Li except the ones your packages "uses". 1518*8c35d5eeSXin Li So you have to stay away from symbols 1519*8c35d5eeSXin Li that are part of the Lisp implementation (since you always "use" that) 1520*8c35d5eeSXin Li and that are part of any other packages you "use", 1521*8c35d5eeSXin Li but otherwise you are free to make up your own names, 1522*8c35d5eeSXin Li even short ones, and not worry about some else 1523*8c35d5eeSXin Li having used the same name. 1524*8c35d5eeSXin Li You're isolated from each other. 1525*8c35d5eeSXin Li </p> 1526*8c35d5eeSXin Li <p> 1527*8c35d5eeSXin Li Your package must not shadow (and thus effectively redefine) 1528*8c35d5eeSXin Li symbols that are part of the Common Lisp language. 1529*8c35d5eeSXin Li There are certain exceptions, 1530*8c35d5eeSXin Li but they should be very well-justified and extremely rare: 1531*8c35d5eeSXin Li </p> 1532*8c35d5eeSXin Li <ul> 1533*8c35d5eeSXin Li <li> 1534*8c35d5eeSXin Li If you are explicitly replacing a Common Lisp symbol 1535*8c35d5eeSXin Li by a safer or more featureful version. 1536*8c35d5eeSXin Li </li> 1537*8c35d5eeSXin Li <li> 1538*8c35d5eeSXin Li If you are defining a package not meant to be "used", 1539*8c35d5eeSXin Li and have a good reason to export a symbol 1540*8c35d5eeSXin Li that clashes with Common Lisp, 1541*8c35d5eeSXin Li such as <code>log:error</code> and <code>log:warn</code> 1542*8c35d5eeSXin Li and so on. 1543*8c35d5eeSXin Li </li> 1544*8c35d5eeSXin Li </ul> 1545*8c35d5eeSXin Li </BODY> 1546*8c35d5eeSXin Li </STYLEPOINT> 1547*8c35d5eeSXin Li</CATEGORY> 1548*8c35d5eeSXin Li 1549*8c35d5eeSXin Li<CATEGORY title="Language usage guidelines"> 1550*8c35d5eeSXin Li <STYLEPOINT title="Mostly Functional Style"> 1551*8c35d5eeSXin Li <SUMMARY> 1552*8c35d5eeSXin Li You should avoid side-effects when they are not necessary. 1553*8c35d5eeSXin Li </SUMMARY> 1554*8c35d5eeSXin Li <BODY> 1555*8c35d5eeSXin Li <p> 1556*8c35d5eeSXin Li Lisp is best used as a "mostly functional" language. 1557*8c35d5eeSXin Li </p> 1558*8c35d5eeSXin Li <p> 1559*8c35d5eeSXin Li Avoid modifying local variables, try rebinding instead. 1560*8c35d5eeSXin Li </p> 1561*8c35d5eeSXin Li <p> 1562*8c35d5eeSXin Li Avoid creating objects and the SETFing their slots. 1563*8c35d5eeSXin Li It's better to set the slots during initialization. 1564*8c35d5eeSXin Li </p> 1565*8c35d5eeSXin Li <p> 1566*8c35d5eeSXin Li Make classes as immutable as possible, that is, avoid giving slots 1567*8c35d5eeSXin Li setter functions if at all possible. 1568*8c35d5eeSXin Li </p> 1569*8c35d5eeSXin Li <p> 1570*8c35d5eeSXin Li Using a mostly functional style makes it much easier 1571*8c35d5eeSXin Li to write concurrent code that is thread-safe. 1572*8c35d5eeSXin Li It also makes it easier to test the code. 1573*8c35d5eeSXin Li </p> 1574*8c35d5eeSXin Li </BODY> 1575*8c35d5eeSXin Li </STYLEPOINT> 1576*8c35d5eeSXin Li <STYLEPOINT title="Recursion"> 1577*8c35d5eeSXin Li <SUMMARY> 1578*8c35d5eeSXin Li You should favor iteration over recursion. 1579*8c35d5eeSXin Li </SUMMARY> 1580*8c35d5eeSXin Li <BODY> 1581*8c35d5eeSXin Li <p> 1582*8c35d5eeSXin Li Common Lisp systems are not required to implement 1583*8c35d5eeSXin Li function calls from tail positions without leaking stack space 1584*8c35d5eeSXin Li — which is known as proper tail calls (PTC), 1585*8c35d5eeSXin Li tail call elimination (TCE), 1586*8c35d5eeSXin Li or tail call optimization (TCO). 1587*8c35d5eeSXin Li This means that indefinite recursion through tail calls 1588*8c35d5eeSXin Li may quickly blow out the stack, 1589*8c35d5eeSXin Li which hampers functional programming. 1590*8c35d5eeSXin Li Still, most serious implementations (including SBCL and CCL) 1591*8c35d5eeSXin Li do implement proper tail calls, but with restrictions: 1592*8c35d5eeSXin Li </p> 1593*8c35d5eeSXin Li <ul> 1594*8c35d5eeSXin Li <li> 1595*8c35d5eeSXin Li The <code>(DECLARE (OPTIMIZE ...))</code> settings 1596*8c35d5eeSXin Li must favor <code>SPEED</code> enough and 1597*8c35d5eeSXin Li not favor <code>DEBUG</code> too much, 1598*8c35d5eeSXin Li for some compiler-dependent meanings of "enough" and "too much". 1599*8c35d5eeSXin Li (For instance, in SBCL, you should avoid <code>(SPEED 0)</code> 1600*8c35d5eeSXin Li and <code>(DEBUG 3)</code> to achieve proper tail calls.) 1601*8c35d5eeSXin Li </li> 1602*8c35d5eeSXin Li <li> 1603*8c35d5eeSXin Li There should not be dynamic bindings around the call 1604*8c35d5eeSXin Li (even though some Scheme compilers are able to properly treat 1605*8c35d5eeSXin Li such dynamic bindings, called parameters in Scheme parlance). 1606*8c35d5eeSXin Li </li> 1607*8c35d5eeSXin Li </ul> 1608*8c35d5eeSXin Li <p> 1609*8c35d5eeSXin Li For compatibility with all compilers and optimization settings, 1610*8c35d5eeSXin Li and to avoid stack overflow when debugging, 1611*8c35d5eeSXin Li you should prefer iteration or the built in mapping functions 1612*8c35d5eeSXin Li to relying on proper tail calls. 1613*8c35d5eeSXin Li </p> 1614*8c35d5eeSXin Li <p> 1615*8c35d5eeSXin Li If you do rely on proper tail calls, 1616*8c35d5eeSXin Li you must prominently document the fact, 1617*8c35d5eeSXin Li and take appropriate measures to ensure an appropriate compiler is used 1618*8c35d5eeSXin Li with appropriate optimization settings. 1619*8c35d5eeSXin Li For fully portable code, you may have to use trampolines instead. 1620*8c35d5eeSXin Li </p> 1621*8c35d5eeSXin Li </BODY> 1622*8c35d5eeSXin Li </STYLEPOINT> 1623*8c35d5eeSXin Li <STYLEPOINT title="Special variables"> 1624*8c35d5eeSXin Li <SUMMARY> 1625*8c35d5eeSXin Li Use special variables sparingly. 1626*8c35d5eeSXin Li </SUMMARY> 1627*8c35d5eeSXin Li <BODY> 1628*8c35d5eeSXin Li <p> 1629*8c35d5eeSXin Li Using Lisp "special" (dynamically bound) variables 1630*8c35d5eeSXin Li as implicit arguments to functions should be used sparingly, 1631*8c35d5eeSXin Li and only in cases where it won't surprise the person reading the code, 1632*8c35d5eeSXin Li and where it offers significant benefits. 1633*8c35d5eeSXin Li </p> 1634*8c35d5eeSXin Li <p> 1635*8c35d5eeSXin Li Indeed, each special variable constitutes state. 1636*8c35d5eeSXin Li Developers have to mentally track the state of all relevant variables 1637*8c35d5eeSXin Li when trying to understand what the code does and how it does it; 1638*8c35d5eeSXin Li tests have to be written and run with all relevant combinations; 1639*8c35d5eeSXin Li to isolate some activity, care has to be taken to locally bind 1640*8c35d5eeSXin Li all relevant variables, including those of indirectly used modules. 1641*8c35d5eeSXin Li They can hide precious information from being printed in a backtrace. 1642*8c35d5eeSXin Li Not only is there overhead associated to each new variable, 1643*8c35d5eeSXin Li but interactions between variables 1644*8c35d5eeSXin Li can make the code exponentially more complex 1645*8c35d5eeSXin Li as the number of such variables increases. 1646*8c35d5eeSXin Li The benefits have to match the costs. 1647*8c35d5eeSXin Li </p> 1648*8c35d5eeSXin Li <p> 1649*8c35d5eeSXin Li Note though that a Lisp special variable is not a global variable 1650*8c35d5eeSXin Li in the sense of a global variable in, say, BASIC or C. 1651*8c35d5eeSXin Li As special variables can be dynamically bound to a local value, 1652*8c35d5eeSXin Li they are much more powerful than 1653*8c35d5eeSXin Li global value cells where all users necessarily interfere with each other. 1654*8c35d5eeSXin Li </p> 1655*8c35d5eeSXin Li <p> 1656*8c35d5eeSXin Li Good candidates for such special variables 1657*8c35d5eeSXin Li are items for which "the current" can be naturally used as prefix, 1658*8c35d5eeSXin Li such as "the current database connection" or 1659*8c35d5eeSXin Li "the current business data source". 1660*8c35d5eeSXin Li They are singletons as far as the rest of the code is concerned, 1661*8c35d5eeSXin Li and often passing them as an explicit argument 1662*8c35d5eeSXin Li does not add anything to the readability or maintainability 1663*8c35d5eeSXin Li of the source code in question. 1664*8c35d5eeSXin Li </p> 1665*8c35d5eeSXin Li <p> 1666*8c35d5eeSXin Li They can make it easier to write code that can be refactored. 1667*8c35d5eeSXin Li If you have a request processing chain, 1668*8c35d5eeSXin Li with a number of layers that all operate upon a "current" request, 1669*8c35d5eeSXin Li passing the request object explicitly to every function 1670*8c35d5eeSXin Li requires that every function in the chain have a request argument. 1671*8c35d5eeSXin Li Factoring out code into new functions often requires 1672*8c35d5eeSXin Li that these functions also have this argument, 1673*8c35d5eeSXin Li which clutters the code with boilerplate. 1674*8c35d5eeSXin Li </p> 1675*8c35d5eeSXin Li <p> 1676*8c35d5eeSXin Li You should treat special variables 1677*8c35d5eeSXin Li as though they are per-thread variables. 1678*8c35d5eeSXin Li By default, you should leave a special variable 1679*8c35d5eeSXin Li with no top-level binding at all, 1680*8c35d5eeSXin Li and each thread of control 1681*8c35d5eeSXin Li that needs the variable should bind it explicitly. 1682*8c35d5eeSXin Li This will mean that any incorrect use of the variable 1683*8c35d5eeSXin Li will result in an "unbound variable" error, and 1684*8c35d5eeSXin Li each thread will see its own value for the variable. 1685*8c35d5eeSXin Li Variables with a default global value should usually be 1686*8c35d5eeSXin Li locally bound at thread creation time. 1687*8c35d5eeSXin Li You should use suitable infrastructure 1688*8c35d5eeSXin Li to automate the appropriate declaration of such variables. 1689*8c35d5eeSXin Li </p> 1690*8c35d5eeSXin Li 1691*8c35d5eeSXin Li </BODY> 1692*8c35d5eeSXin Li </STYLEPOINT> 1693*8c35d5eeSXin Li <STYLEPOINT title="Assignment"> 1694*8c35d5eeSXin Li <SUMMARY> 1695*8c35d5eeSXin Li Be consistent in assignment forms. 1696*8c35d5eeSXin Li </SUMMARY> 1697*8c35d5eeSXin Li <BODY> 1698*8c35d5eeSXin Li <p> 1699*8c35d5eeSXin Li There are several styles for dealing with assignment and side-effects; 1700*8c35d5eeSXin Li whichever a given package is using, 1701*8c35d5eeSXin Li keep using the same consistently when hacking said package. 1702*8c35d5eeSXin Li Pick a style that makes sense when starting a new package. 1703*8c35d5eeSXin Li </p> 1704*8c35d5eeSXin Li <p> 1705*8c35d5eeSXin Li Regarding multiple assignment in a same form, there are two schools: 1706*8c35d5eeSXin Li the first style groups as many assignments as possible into a single 1707*8c35d5eeSXin Li <code>SETF</code> or <code>PSETF</code> form 1708*8c35d5eeSXin Li thus minimizing the number of forms with side-effects; 1709*8c35d5eeSXin Li the second style splits assignments into as many individual 1710*8c35d5eeSXin Li <code>SETF</code> (or <code>SETQ</code>, see below) forms as possible, 1711*8c35d5eeSXin Li to maximize the chances of locating forms that modify a kind of place 1712*8c35d5eeSXin Li by grepping for <code>(setf (foo ...</code>. 1713*8c35d5eeSXin Li A grep pattern must actually contain as many place-modifying forms 1714*8c35d5eeSXin Li as you may use in your programs, which may make this rationale either 1715*8c35d5eeSXin Li convincing or moot depending on the rest of the style of your code. 1716*8c35d5eeSXin Li You should follow the convention used in the package you are hacking. 1717*8c35d5eeSXin Li We recommend the first convention for new packages. 1718*8c35d5eeSXin Li </p> 1719*8c35d5eeSXin Li <p> 1720*8c35d5eeSXin Li Regarding <code>SETF</code> and <code>SETQ</code>, 1721*8c35d5eeSXin Li there are two schools: 1722*8c35d5eeSXin Li this first regards <code>SETQ</code> 1723*8c35d5eeSXin Li as an archaic implementation detail, 1724*8c35d5eeSXin Li and avoids it entirely in favor of <code>SETF</code>; 1725*8c35d5eeSXin Li the second regards <code>SETF</code> 1726*8c35d5eeSXin Li as an additional layer of complexity, 1727*8c35d5eeSXin Li and avoids it in favor of <code>SETQ</code> whenever possible 1728*8c35d5eeSXin Li (i.e. whenever the assigned place is a variable or symbol-macro). 1729*8c35d5eeSXin Li You should follow the convention used in the package you are hacking. 1730*8c35d5eeSXin Li We recommend the first convention for new packages. 1731*8c35d5eeSXin Li </p> 1732*8c35d5eeSXin Li <p> 1733*8c35d5eeSXin Li In the spirit of a mostly pure functional style, 1734*8c35d5eeSXin Li which makes testing and maintenance easier, 1735*8c35d5eeSXin Li we invite you to consider how to do things with the fewest assignments required. 1736*8c35d5eeSXin Li </p> 1737*8c35d5eeSXin Li </BODY> 1738*8c35d5eeSXin Li </STYLEPOINT> 1739*8c35d5eeSXin Li <STYLEPOINT title="Assertions and Conditions"> 1740*8c35d5eeSXin Li <SUMMARY> 1741*8c35d5eeSXin Li You must make proper usage of assertions and conditions. 1742*8c35d5eeSXin Li </SUMMARY> 1743*8c35d5eeSXin Li <BODY> 1744*8c35d5eeSXin Li <ul> 1745*8c35d5eeSXin Li <li> 1746*8c35d5eeSXin Li <code>ASSERT</code> should be used ONLY to detect internal bugs. 1747*8c35d5eeSXin Li Code should <code>ASSERT</code> invariants whose failure indicates 1748*8c35d5eeSXin Li that the software is itself broken. 1749*8c35d5eeSXin Li Incorrect input should be handled properly at runtime, 1750*8c35d5eeSXin Li and must not cause an assertion violation. 1751*8c35d5eeSXin Li The audience for an <code>ASSERT</code> failure is a developer. 1752*8c35d5eeSXin Li Do not use the data-form and argument-form in <code>ASSERT</code> 1753*8c35d5eeSXin Li to specify a condition to signal. 1754*8c35d5eeSXin Li It's fine to use them to print out a message for debugging purposes 1755*8c35d5eeSXin Li (and since it's only for debugging, there's no issue of 1756*8c35d5eeSXin Li internationalization). 1757*8c35d5eeSXin Li </li> 1758*8c35d5eeSXin Li <li> 1759*8c35d5eeSXin Li <code>CHECK-TYPE</code>, 1760*8c35d5eeSXin Li <code>ETYPECASE</code> are also forms of assertion. 1761*8c35d5eeSXin Li When one of these fails, that's a detected bug. 1762*8c35d5eeSXin Li You should prefer to use <code>CHECK-TYPE</code> 1763*8c35d5eeSXin Li over (DECLARE (TYPE ...)) 1764*8c35d5eeSXin Li for the inputs of functions. 1765*8c35d5eeSXin Li </li> 1766*8c35d5eeSXin Li <li> 1767*8c35d5eeSXin Li Your code should use assertions and type checks liberally. 1768*8c35d5eeSXin Li The sooner a bug is discovered, the better! 1769*8c35d5eeSXin Li Only code in the critical path for performance 1770*8c35d5eeSXin Li and internal helpers should eschew 1771*8c35d5eeSXin Li explicit assertions and type checks. 1772*8c35d5eeSXin Li </li> 1773*8c35d5eeSXin Li <li> 1774*8c35d5eeSXin Li Invalid input, such as files that are read 1775*8c35d5eeSXin Li but do not conform to the expected format, 1776*8c35d5eeSXin Li should not be treated as assertion violations. 1777*8c35d5eeSXin Li Always check to make sure that input is valid, 1778*8c35d5eeSXin Li and take appropriate action if it is not, 1779*8c35d5eeSXin Li such as signalling a real error. 1780*8c35d5eeSXin Li </li> 1781*8c35d5eeSXin Li <li> 1782*8c35d5eeSXin Li <code>ERROR</code> should be used 1783*8c35d5eeSXin Li to detect problems with user data, requests, permissions, etc., 1784*8c35d5eeSXin Li or to report "unusual outcomes" to the caller. 1785*8c35d5eeSXin Li </li> 1786*8c35d5eeSXin Li <li> 1787*8c35d5eeSXin Li <code>ERROR</code> should always be called 1788*8c35d5eeSXin Li with an explicit condition type; 1789*8c35d5eeSXin Li it should never simply be called with a string. 1790*8c35d5eeSXin Li This enables internationalization. 1791*8c35d5eeSXin Li </li> 1792*8c35d5eeSXin Li <li> 1793*8c35d5eeSXin Li Functions that report unusual outcomes 1794*8c35d5eeSXin Li by signaling a condition should say so explicitly in their contracts 1795*8c35d5eeSXin Li (their textual descriptions, in documentation and docstrings etc.). 1796*8c35d5eeSXin Li When a function signals a condition 1797*8c35d5eeSXin Li that is not specified by its contract, that's a bug. 1798*8c35d5eeSXin Li The contract should specify the condition class(es) clearly. 1799*8c35d5eeSXin Li The function may then signal any condition 1800*8c35d5eeSXin Li that is a type-of any of those conditions. 1801*8c35d5eeSXin Li That is, signaling instances of subclasses 1802*8c35d5eeSXin Li of the documented condition classes is fine. 1803*8c35d5eeSXin Li </li> 1804*8c35d5eeSXin Li <li> 1805*8c35d5eeSXin Li Complex bug-checks may need to use <code>ERROR</code> 1806*8c35d5eeSXin Li instead of <code>ASSERT</code>. 1807*8c35d5eeSXin Li 1808*8c35d5eeSXin Li </li> 1809*8c35d5eeSXin Li <li> 1810*8c35d5eeSXin Li When writing a server, you must not call <code>WARN</code>. 1811*8c35d5eeSXin Li Instead, you should use the appropriate logging framework. 1812*8c35d5eeSXin Li 1813*8c35d5eeSXin Li </li> 1814*8c35d5eeSXin Li <li> 1815*8c35d5eeSXin Li Code must not call <code>SIGNAL</code>. 1816*8c35d5eeSXin Li Instead, use <code>ERROR</code> or <code>ASSERT</code>. 1817*8c35d5eeSXin Li </li> 1818*8c35d5eeSXin Li <li> 1819*8c35d5eeSXin Li Code should not use <code>THROW</code> and <code>CATCH</code>; 1820*8c35d5eeSXin Li instead use the <code>restart</code> facility. 1821*8c35d5eeSXin Li </li> 1822*8c35d5eeSXin Li <li> 1823*8c35d5eeSXin Li Code should not generically handle all conditions, 1824*8c35d5eeSXin Li e.g. type <code>T</code>, or use <code>IGNORE-ERRORS</code>. 1825*8c35d5eeSXin Li Instead, let unknown conditions propagate to 1826*8c35d5eeSXin Li the standard ultimate handler for processing. 1827*8c35d5eeSXin Li 1828*8c35d5eeSXin Li </li> 1829*8c35d5eeSXin Li <li> 1830*8c35d5eeSXin Li There are a few places where handling all conditions is appropriate, 1831*8c35d5eeSXin Li but they are rare. 1832*8c35d5eeSXin Li The problem is that handling all conditions can mask program bugs. 1833*8c35d5eeSXin Li If you <em>do</em> need to handle "all conditions", 1834*8c35d5eeSXin Li you MUST handle only <code>ERROR</code>, <em>not</em> <code>T</code> 1835*8c35d5eeSXin Li and not <code>SERIOUS-CONDITION</code>. 1836*8c35d5eeSXin Li (This is notably because CCL's process shutdown 1837*8c35d5eeSXin Li depends on being able to signal <code>process-reset</code> 1838*8c35d5eeSXin Li and have it handled by CCL's handler, 1839*8c35d5eeSXin Li so we must not interpose our own handler.) 1840*8c35d5eeSXin Li </li> 1841*8c35d5eeSXin Li <li> 1842*8c35d5eeSXin Li <code>(error (make-condition 'foo-error ...))</code> 1843*8c35d5eeSXin Li is equivalent to <code>(error 'foo-error ...)</code> — 1844*8c35d5eeSXin Li code must use the shorter form. 1845*8c35d5eeSXin Li </li> 1846*8c35d5eeSXin Li <li> 1847*8c35d5eeSXin Li Code should not signal conditions from inside the cleanup form of 1848*8c35d5eeSXin Li <code>UNWIND-PROTECT</code> 1849*8c35d5eeSXin Li (unless they are always handled inside the cleanup form), 1850*8c35d5eeSXin Li or otherwise do non-local exits from cleanup handlers 1851*8c35d5eeSXin Li outside of the handler e.g. <code>INVOKE-RESTART</code>. 1852*8c35d5eeSXin Li </li> 1853*8c35d5eeSXin Li <li> 1854*8c35d5eeSXin Li Do not clean up by resignaling. 1855*8c35d5eeSXin Li If you do that, and the condition is not handled, 1856*8c35d5eeSXin Li the stack trace will halt at the point of the resignal, 1857*8c35d5eeSXin Li hiding the rest. 1858*8c35d5eeSXin Li And the rest is the part we really care about! 1859*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 1860*8c35d5eeSXin Li ;; Bad 1861*8c35d5eeSXin Li (handler-case 1862*8c35d5eeSXin Li (catch 'ticket-at 1863*8c35d5eeSXin Li (etd-process-blocks)) 1864*8c35d5eeSXin Li (error (c) 1865*8c35d5eeSXin Li (reset-parser-values) 1866*8c35d5eeSXin Li (error c))) 1867*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 1868*8c35d5eeSXin Li <CODE_SNIPPET> 1869*8c35d5eeSXin Li ;; Better 1870*8c35d5eeSXin Li (unwind-protect 1871*8c35d5eeSXin Li (catch 'ticket-at 1872*8c35d5eeSXin Li (etd-process-blocks)) 1873*8c35d5eeSXin Li (reset-parser-values)) 1874*8c35d5eeSXin Li </CODE_SNIPPET> 1875*8c35d5eeSXin Li </li> 1876*8c35d5eeSXin Li </ul> 1877*8c35d5eeSXin Li </BODY> 1878*8c35d5eeSXin Li </STYLEPOINT> 1879*8c35d5eeSXin Li <STYLEPOINT title="Type Checking"> 1880*8c35d5eeSXin Li <SUMMARY> 1881*8c35d5eeSXin Li If you know the type of something, you should make it explicit 1882*8c35d5eeSXin Li in order to enable compile-time and run-time sanity-checking. 1883*8c35d5eeSXin Li </SUMMARY> 1884*8c35d5eeSXin Li <BODY> 1885*8c35d5eeSXin Li 1886*8c35d5eeSXin Li <p> 1887*8c35d5eeSXin Li If your function is using a special variable as an implicit argument, 1888*8c35d5eeSXin Li it's good to put in a <code>CHECK-TYPE</code> for the special variable, 1889*8c35d5eeSXin Li for two reasons: 1890*8c35d5eeSXin Li to clue in the person reading the code 1891*8c35d5eeSXin Li that this variable is being used implicitly as an argument, 1892*8c35d5eeSXin Li and also to help detect bugs. 1893*8c35d5eeSXin Li </p> 1894*8c35d5eeSXin Li 1895*8c35d5eeSXin Li <p> 1896*8c35d5eeSXin Li Using <code>(declare (type ...))</code> 1897*8c35d5eeSXin Li is the least-desirable mechanism to use 1898*8c35d5eeSXin Li because, as Scott McKay puts it: 1899*8c35d5eeSXin Li </p> 1900*8c35d5eeSXin Li <blockquote> 1901*8c35d5eeSXin Li <p> 1902*8c35d5eeSXin Li The fact is, <code>(declare (type ...))</code> does different things 1903*8c35d5eeSXin Li depending on the compiler settings of speed, safety, etc. 1904*8c35d5eeSXin Li In some compilers, when speed is greater than safety, 1905*8c35d5eeSXin Li <code>(declare (type ...))</code> will tell the compiler 1906*8c35d5eeSXin Li "please assume that these variables have these types" 1907*8c35d5eeSXin Li <em>without</em> generating any type-checks. 1908*8c35d5eeSXin Li That is, if some variable has the value <code>1432</code> in it, 1909*8c35d5eeSXin Li and you declare it to be of type <code>string</code>, 1910*8c35d5eeSXin Li the compiler might just go ahead and use it as though it's a string. 1911*8c35d5eeSXin Li </p> 1912*8c35d5eeSXin Li <p> 1913*8c35d5eeSXin Li Moral: don't use <code>(declare (type ...))</code> 1914*8c35d5eeSXin Li to declare the contract of any API functions, 1915*8c35d5eeSXin Li it's not the right thing. 1916*8c35d5eeSXin Li Sure, use it for "helper" functions, but not API functions. 1917*8c35d5eeSXin Li </p> 1918*8c35d5eeSXin Li </blockquote> 1919*8c35d5eeSXin Li <p> 1920*8c35d5eeSXin Li You should, of course, use appropriate declarations 1921*8c35d5eeSXin Li in internal low-level functions 1922*8c35d5eeSXin Li where these declarations are used for optimization. 1923*8c35d5eeSXin Li When you do, however, see our recommendations for 1924*8c35d5eeSXin Li <a href="#Unsafe_Operations">Unsafe Operations</a>. 1925*8c35d5eeSXin Li </p> 1926*8c35d5eeSXin Li </BODY> 1927*8c35d5eeSXin Li </STYLEPOINT> 1928*8c35d5eeSXin Li <STYLEPOINT title="CLOS"> 1929*8c35d5eeSXin Li <SUMMARY> 1930*8c35d5eeSXin Li Use CLOS appropriately. 1931*8c35d5eeSXin Li </SUMMARY> 1932*8c35d5eeSXin Li <BODY> 1933*8c35d5eeSXin Li <p> 1934*8c35d5eeSXin Li When a generic function is intended to be called from other 1935*8c35d5eeSXin Li modules (other parts of the code), there should be an 1936*8c35d5eeSXin Li explicit <code>DEFGENERIC</code> form, 1937*8c35d5eeSXin Li with a <code>:DOCUMENTATION</code> string 1938*8c35d5eeSXin Li explaining the generic contract of the function 1939*8c35d5eeSXin Li (as opposed to its behavior for some specific class). 1940*8c35d5eeSXin Li It's generally good to do explicit <code>DEFGENERIC</code> forms, 1941*8c35d5eeSXin Li but for module entry points it is mandatory. 1942*8c35d5eeSXin Li </p> 1943*8c35d5eeSXin Li <p> 1944*8c35d5eeSXin Li When the argument list of a generic function includes 1945*8c35d5eeSXin Li <code>&KEY</code>, 1946*8c35d5eeSXin Li the <code>DEFGENERIC</code> should always explicitly list 1947*8c35d5eeSXin Li all of the keyword arguments that are acceptable, 1948*8c35d5eeSXin Li and explain what they mean. 1949*8c35d5eeSXin Li (Common Lisp does not require this, but it is good form, 1950*8c35d5eeSXin Li and it may avoid spurious warnings on SBCL.) 1951*8c35d5eeSXin Li </p> 1952*8c35d5eeSXin Li <p> 1953*8c35d5eeSXin Li You should avoid <code>SLOT-VALUE</code> and <code>WITH-SLOTS</code>, 1954*8c35d5eeSXin Li unless you absolutely intend to circumvent 1955*8c35d5eeSXin Li any sort of method combination that might be in effect for the slot. 1956*8c35d5eeSXin Li Rare exceptions include <code>INITIALIZE-INSTANCE</code> 1957*8c35d5eeSXin Li and <code>PRINT-OBJECT</code> methods and 1958*8c35d5eeSXin Li accessing normally hidden slots in the low-level implementation of 1959*8c35d5eeSXin Li methods that provide user-visible abstractions. 1960*8c35d5eeSXin Li Otherwise, you should use accessors, 1961*8c35d5eeSXin Li <code>WITH-ACCESSORS</code> 1962*8c35d5eeSXin Li </p> 1963*8c35d5eeSXin Li 1964*8c35d5eeSXin Li <p> 1965*8c35d5eeSXin Li Accessor names generally follow a convention of 1966*8c35d5eeSXin Li <code><protocol-name>-<slot-name></code>, 1967*8c35d5eeSXin Li where a "protocol" in this case loosely indicates 1968*8c35d5eeSXin Li a set of functions with well-defined behavior. 1969*8c35d5eeSXin Li </p> 1970*8c35d5eeSXin Li <p> 1971*8c35d5eeSXin Li No implication of a formal "protocol" concept is necessarily intended, 1972*8c35d5eeSXin Li much less first-class "protocol" objects. 1973*8c35d5eeSXin Li However, there may indeed be an abstract CLOS class 1974*8c35d5eeSXin Li or an 1975*8c35d5eeSXin Li <a href="https://common-lisp.net/~frideau/lil-ilc2012/lil-ilc2012.html">Interface-Passing Style</a> interface 1976*8c35d5eeSXin Li that embodies the protocol. 1977*8c35d5eeSXin Li Further (sub)classes or (sub)interfaces may then implement 1978*8c35d5eeSXin Li all or part of a protocol by defining 1979*8c35d5eeSXin Li some methods for (generic) functions in the protocol, 1980*8c35d5eeSXin Li including readers and writers. 1981*8c35d5eeSXin Li </p> 1982*8c35d5eeSXin Li <p> 1983*8c35d5eeSXin Li For example, if there were a notional protocol called 1984*8c35d5eeSXin Li is <code>pnr</code> with accessors <code>pnr-segments</code> 1985*8c35d5eeSXin Li and <code>pnr-passengers</code>, then 1986*8c35d5eeSXin Li the classes <code>air-pnr</code>, <code>hotel-pnr</code> and 1987*8c35d5eeSXin Li <code>car-pnr</code> could each reasonably implement 1988*8c35d5eeSXin Li methods for <code>pnr-segments</code> and <code>pnr-passengers</code> 1989*8c35d5eeSXin Li as accessors. 1990*8c35d5eeSXin Li </p> 1991*8c35d5eeSXin Li <p> 1992*8c35d5eeSXin Li By default, an abstract base class name is used 1993*8c35d5eeSXin Li as the notional protocol name, so accessor names default 1994*8c35d5eeSXin Li to <code><class-name>-<slot-name></code>; 1995*8c35d5eeSXin Li while such names are thus quite prevalent, 1996*8c35d5eeSXin Li this form is neither required nor even preferred. 1997*8c35d5eeSXin Li In general, it contributes to "symbol bloat", 1998*8c35d5eeSXin Li and in many cases has led to a proliferation of "trampoline" methods. 1999*8c35d5eeSXin Li </p> 2000*8c35d5eeSXin Li <p> 2001*8c35d5eeSXin Li Accessors named <code><slot-name>-of</code> should not be used. 2002*8c35d5eeSXin Li </p> 2003*8c35d5eeSXin Li <p> 2004*8c35d5eeSXin Li Explicit <code>DEFGENERIC</code> forms should be used when there are 2005*8c35d5eeSXin Li (or it is anticipated that there will be) 2006*8c35d5eeSXin Li more than one <code>DEFMETHOD</code> for that generic function. 2007*8c35d5eeSXin Li The reason is that the documentation for the generic function 2008*8c35d5eeSXin Li explains the abstract contract for the function, 2009*8c35d5eeSXin Li as opposed to explaining what an individual method does for 2010*8c35d5eeSXin Li some specific class(es). 2011*8c35d5eeSXin Li </p> 2012*8c35d5eeSXin Li <p> 2013*8c35d5eeSXin Li You must not use generic functions where there is no notional protocol. 2014*8c35d5eeSXin Li To put it more concretely, 2015*8c35d5eeSXin Li if you have more than one generic function that specializes its Nth argument, 2016*8c35d5eeSXin Li the specializing classes should all be descendants of a single class. 2017*8c35d5eeSXin Li Generic functions must not be used for "overloading", 2018*8c35d5eeSXin Li i.e. simply to use the same name for two entirely unrelated types. 2019*8c35d5eeSXin Li </p> 2020*8c35d5eeSXin Li <p> 2021*8c35d5eeSXin Li More precisely, it's not really 2022*8c35d5eeSXin Li whether they descend from a common superclass, 2023*8c35d5eeSXin Li but whether they obey the same "protocol". 2024*8c35d5eeSXin Li That is, the two classes should handle the same set of generic functions, 2025*8c35d5eeSXin Li as if there were an explicit <code>DEFGENERIC</code> for each method. 2026*8c35d5eeSXin Li </p> 2027*8c35d5eeSXin Li <p> 2028*8c35d5eeSXin Li Here's another way to put it. 2029*8c35d5eeSXin Li Suppose you have two classes, A and B, and a generic function F. 2030*8c35d5eeSXin Li There are two methods for F, 2031*8c35d5eeSXin Li which dispatch on an argument being of types A and B. 2032*8c35d5eeSXin Li Is it plausible that there might be a function call somewhere 2033*8c35d5eeSXin Li in the program that calls F, 2034*8c35d5eeSXin Li in which the argument might sometimes, at runtime, 2035*8c35d5eeSXin Li be of class A and other times be of class B? 2036*8c35d5eeSXin Li If not, you probably are overloading and 2037*8c35d5eeSXin Li should not be using a single generic function. 2038*8c35d5eeSXin Li </p> 2039*8c35d5eeSXin Li <p> 2040*8c35d5eeSXin Li We allow one exception to this rule: 2041*8c35d5eeSXin Li it's OK to do overloading 2042*8c35d5eeSXin Li if the corresponding argument "means" the same thing. 2043*8c35d5eeSXin Li Typically one overloading allows an X object, 2044*8c35d5eeSXin Li and the other allows the name of an X object, 2045*8c35d5eeSXin Li which might be a symbol or something. 2046*8c35d5eeSXin Li </p> 2047*8c35d5eeSXin Li <p> 2048*8c35d5eeSXin Li You must not use MOP "intercessory" operations at runtime. 2049*8c35d5eeSXin Li You should not use MOP "intercessory" operations at compile-time. 2050*8c35d5eeSXin Li At runtime, they are at worst a danger, at best a performance issue. 2051*8c35d5eeSXin Li At compile-time, it is usually cleaner that 2052*8c35d5eeSXin Li macros should set things up the right way in one pass 2053*8c35d5eeSXin Li than have to require a second pass of fixups through intercession; 2054*8c35d5eeSXin Li but sometimes, fixups are necessary to resolve forward references, 2055*8c35d5eeSXin Li and intercession is allowed then. 2056*8c35d5eeSXin Li MOP intercession is a great tool for interactive development, 2057*8c35d5eeSXin Li and you may enjoy it while developping and debugging; 2058*8c35d5eeSXin Li but you should not use it in normal applications. 2059*8c35d5eeSXin Li </p> 2060*8c35d5eeSXin Li <p> 2061*8c35d5eeSXin Li If a class definition creates a method 2062*8c35d5eeSXin Li as a <code>:READER</code>, <code>:WRITER</code>, 2063*8c35d5eeSXin Li or <code>:ACCESSOR</code>, 2064*8c35d5eeSXin Li do not redefine that method. 2065*8c35d5eeSXin Li It's OK to add <code>:BEFORE</code>, <code>:AFTER</code>, 2066*8c35d5eeSXin Li and <code>:AROUND</code> methods, 2067*8c35d5eeSXin Li but don't override the primary method. 2068*8c35d5eeSXin Li </p> 2069*8c35d5eeSXin Li <p> 2070*8c35d5eeSXin Li In methods with keyword arguments, 2071*8c35d5eeSXin Li you must always use <code>&KEY</code>, 2072*8c35d5eeSXin Li even if the method does not care about the values of any keys, 2073*8c35d5eeSXin Li and you should never use <code>&ALLOW-OTHER-KEYS</code>. 2074*8c35d5eeSXin Li As long as a keyword is accepted by any method of a generic function, 2075*8c35d5eeSXin Li it's OK to use it in the generic function, 2076*8c35d5eeSXin Li even if the other methods of the same generic function 2077*8c35d5eeSXin Li don't mention it explicitly. 2078*8c35d5eeSXin Li This is particularly important 2079*8c35d5eeSXin Li for <code>INITIALIZE-INSTANCE</code> methods, 2080*8c35d5eeSXin Li since if you did use <code>&ALLOW-OTHER-KEYS</code>, 2081*8c35d5eeSXin Li it would disable error checking for misspelled or wrong keywords 2082*8c35d5eeSXin Li in <code>MAKE-INSTANCE</code> calls! 2083*8c35d5eeSXin Li </p> 2084*8c35d5eeSXin Li 2085*8c35d5eeSXin Li <p> 2086*8c35d5eeSXin Li A typical <code>PRINT-OBJECT</code> method might look like this: 2087*8c35d5eeSXin Li </p> 2088*8c35d5eeSXin Li <CODE_SNIPPET> 2089*8c35d5eeSXin Li (defmethod print-object ((p person) stream) 2090*8c35d5eeSXin Li (print-unprintable-object (p stream :type t :identity t) 2091*8c35d5eeSXin Li (with-slots (first-name last-name) p 2092*8c35d5eeSXin Li (safe-format stream "~a ~a" first-name last-name)))) 2093*8c35d5eeSXin Li </CODE_SNIPPET> 2094*8c35d5eeSXin Li </BODY> 2095*8c35d5eeSXin Li </STYLEPOINT> 2096*8c35d5eeSXin Li</CATEGORY> 2097*8c35d5eeSXin Li 2098*8c35d5eeSXin Li<CATEGORY title="Meta-language guidelines"> 2099*8c35d5eeSXin Li <STYLEPOINT title="Macros"> 2100*8c35d5eeSXin Li <SUMMARY> 2101*8c35d5eeSXin Li Use macros when appropriate, which is often. 2102*8c35d5eeSXin Li Define macros when appropriate, which is seldom. 2103*8c35d5eeSXin Li </SUMMARY> 2104*8c35d5eeSXin Li <BODY> 2105*8c35d5eeSXin Li <p> 2106*8c35d5eeSXin Li Macros bring syntactic abstraction, which is a wonderful thing. 2107*8c35d5eeSXin Li It helps make your code clearer, by describing your intent 2108*8c35d5eeSXin Li without getting bogged in implementation details 2109*8c35d5eeSXin Li (indeed abstracting those details away). 2110*8c35d5eeSXin Li It helps make your code more concise and more readable, 2111*8c35d5eeSXin Li by eliminating both redundancy and irrelevant details. 2112*8c35d5eeSXin Li But it comes at a cost to the reader, 2113*8c35d5eeSXin Li which is learning a new syntactic concept for each macro. 2114*8c35d5eeSXin Li And so it should not be abused. 2115*8c35d5eeSXin Li </p> 2116*8c35d5eeSXin Li <p> 2117*8c35d5eeSXin Li The general conclusion is that there shouldn't be 2118*8c35d5eeSXin Li any recognizable <em>design pattern</em> 2119*8c35d5eeSXin Li in a good Common Lisp program. 2120*8c35d5eeSXin Li The one and only pattern is: <em>use the language</em>, 2121*8c35d5eeSXin Li which includes defining and using syntactic abstractions. 2122*8c35d5eeSXin Li </p> 2123*8c35d5eeSXin Li <p> 2124*8c35d5eeSXin Li Existing macros must be used 2125*8c35d5eeSXin Li whenever they make code clearer 2126*8c35d5eeSXin Li by conveying intent in a more concise way, 2127*8c35d5eeSXin Li which is often. 2128*8c35d5eeSXin Li When a macro is available in your project 2129*8c35d5eeSXin Li that expresses the concept you're using, 2130*8c35d5eeSXin Li you must not write the expansion rather than use the macro. 2131*8c35d5eeSXin Li </p> 2132*8c35d5eeSXin Li <p> 2133*8c35d5eeSXin Li New macros should be defined as appropriate, 2134*8c35d5eeSXin Li which should be seldom, 2135*8c35d5eeSXin Li for common macros have already been provided 2136*8c35d5eeSXin Li by the language and its various libraries, 2137*8c35d5eeSXin Li and your program typically only needs few new ones 2138*8c35d5eeSXin Li relative to its size. 2139*8c35d5eeSXin Li </p> 2140*8c35d5eeSXin Li <p> 2141*8c35d5eeSXin Li You should follow the OAOOM rule of thumb 2142*8c35d5eeSXin Li for deciding when to create a new abstraction, 2143*8c35d5eeSXin Li whether syntactic or not: 2144*8c35d5eeSXin Li if a particular pattern is used more than twice, 2145*8c35d5eeSXin Li it should probably be abstracted away. 2146*8c35d5eeSXin Li A more refined rule to decide when to use abstraction 2147*8c35d5eeSXin Li should take into account 2148*8c35d5eeSXin Li the benefit in term of number of uses and gain at each use, 2149*8c35d5eeSXin Li to the costs in term of having to get used to reading the code. 2150*8c35d5eeSXin Li For syntactic abstractions, costs and benefits to the reader 2151*8c35d5eeSXin Li is usually more important than costs and benefits to the writer, 2152*8c35d5eeSXin Li because good code is usually written once 2153*8c35d5eeSXin Li and read many times by many people 2154*8c35d5eeSXin Li (including the same programmer 2155*8c35d5eeSXin Li who has to maintain the program after having forgotten it). 2156*8c35d5eeSXin Li Yet the cost to the writer of the macro 2157*8c35d5eeSXin Li should also be taken into account; 2158*8c35d5eeSXin Li however, in doing so it should rather be compared 2159*8c35d5eeSXin Li to the cost of the programmer writing other code instead 2160*8c35d5eeSXin Li that may have higher benefits. 2161*8c35d5eeSXin Li </p> 2162*8c35d5eeSXin Li <p> 2163*8c35d5eeSXin Li Using Lisp macros properly requires taste. 2164*8c35d5eeSXin Li Avoid writing complicated macros 2165*8c35d5eeSXin Li unless the benefit clearly outweighs the cost. 2166*8c35d5eeSXin Li It takes more effort for your fellow developers to learn your macro, 2167*8c35d5eeSXin Li so you should only use a macro if the gain in expressiveness 2168*8c35d5eeSXin Li is big enough to justify that cost. 2169*8c35d5eeSXin Li As usual, feel free to consult your colleagues if you're not sure, 2170*8c35d5eeSXin Li since without a lot of Lisp experience, 2171*8c35d5eeSXin Li it can be hard to make this judgment. 2172*8c35d5eeSXin Li </p> 2173*8c35d5eeSXin Li <p> 2174*8c35d5eeSXin Li You must never use a macro where a function will do. 2175*8c35d5eeSXin Li That is, if the semantics of what you are writing 2176*8c35d5eeSXin Li conforms to the semantics of a function, 2177*8c35d5eeSXin Li then you must write it as a function rather than a macro. 2178*8c35d5eeSXin Li </p> 2179*8c35d5eeSXin Li <p> 2180*8c35d5eeSXin Li You must not transform a function into a macro for performance reasons. 2181*8c35d5eeSXin Li If profiling shows that you have a performance problem 2182*8c35d5eeSXin Li with a specific function <code>FOO</code>, 2183*8c35d5eeSXin Li document the need and profiling-results appropriately, 2184*8c35d5eeSXin Li and 2185*8c35d5eeSXin Li <code>(declaim (inline foo))</code>. 2186*8c35d5eeSXin Li </p> 2187*8c35d5eeSXin Li 2188*8c35d5eeSXin Li <p> 2189*8c35d5eeSXin Li You can also use a compiler-macro 2190*8c35d5eeSXin Li as a way to speed up function execution 2191*8c35d5eeSXin Li by specifying a source-to-source transformation. 2192*8c35d5eeSXin Li Beware that it interferes with tracing the optimized function. 2193*8c35d5eeSXin Li </p> 2194*8c35d5eeSXin Li <p> 2195*8c35d5eeSXin Li When you write a macro-defining macro 2196*8c35d5eeSXin Li (a macro that generates macros), 2197*8c35d5eeSXin Li document and comment it particularly clearly, 2198*8c35d5eeSXin Li since these are harder to understand. 2199*8c35d5eeSXin Li </p> 2200*8c35d5eeSXin Li <p> 2201*8c35d5eeSXin Li You must not install new reader macros 2202*8c35d5eeSXin Li without a consensus among the developers of your system. 2203*8c35d5eeSXin Li Reader macros must not leak out of the system that uses them 2204*8c35d5eeSXin Li to clients of that system or other systems used in the same project. 2205*8c35d5eeSXin Li You must use software such as 2206*8c35d5eeSXin Li <code>cl-syntax</code> or <code>named-readtables</code> 2207*8c35d5eeSXin Li to control how reader macros are used. 2208*8c35d5eeSXin Li This clients who desire it may use the same reader macros as you do. 2209*8c35d5eeSXin Li In any case, your system must be usable 2210*8c35d5eeSXin Li even to clients who do not use these reader macros. 2211*8c35d5eeSXin Li </p> 2212*8c35d5eeSXin Li <p> 2213*8c35d5eeSXin Li If your macro has a parameter that is a Lisp form 2214*8c35d5eeSXin Li that will be evaluated when the expanded code is run, 2215*8c35d5eeSXin Li you should name the parameter with the suffix <code>-form</code>. 2216*8c35d5eeSXin Li This convention helps make it clearer to the macro's user 2217*8c35d5eeSXin Li which parameters are Lisp forms to be evaluated, and which are not. 2218*8c35d5eeSXin Li The common names <code>body</code> and <code>end</code> are 2219*8c35d5eeSXin Li exceptions to this rule. 2220*8c35d5eeSXin Li </p> 2221*8c35d5eeSXin Li <p> 2222*8c35d5eeSXin Li You should follow the so-called <code>CALL-WITH</code> style when it applies. 2223*8c35d5eeSXin Li This style is explained at length in 2224*8c35d5eeSXin Li <a href="http://random-state.net/log/3390120648.html">http://random-state.net/log/3390120648.html</a>. 2225*8c35d5eeSXin Li The general principle is that the macro is strictly limited to processing the syntax, 2226*8c35d5eeSXin Li and as much of the semantics as possible is kept in normal functions. 2227*8c35d5eeSXin Li Therefore, a macro <code>WITH-<em>FOO</em></code> is often limited to 2228*8c35d5eeSXin Li generating a call to an auxiliary function 2229*8c35d5eeSXin Li <code>CALL-WITH-<em>FOO</em></code> 2230*8c35d5eeSXin Li with arguments deduced from the macro arguments. 2231*8c35d5eeSXin Li Macro <code>&body</code> arguments are typically 2232*8c35d5eeSXin Li wrapped into a lambda expression of which they become the body, 2233*8c35d5eeSXin Li which is passed as one of the arguments of the auxiliary function. 2234*8c35d5eeSXin Li </p> 2235*8c35d5eeSXin Li <p> 2236*8c35d5eeSXin Li The separation of syntactic and semantic concerns 2237*8c35d5eeSXin Li is a general principle of style that applies 2238*8c35d5eeSXin Li beyond the case of <code>WITH-</code> macros. 2239*8c35d5eeSXin Li Its advantages are many. 2240*8c35d5eeSXin Li By keeping semantics outside the macro, 2241*8c35d5eeSXin Li the macro is made simpler, easier to get right, and less subject to change, 2242*8c35d5eeSXin Li which makes it easier to develop and maintain. 2243*8c35d5eeSXin Li The semantics is written in a simpler language — one without staging — 2244*8c35d5eeSXin Li which also makes it easier to develop and maintain. 2245*8c35d5eeSXin Li It becomes possible to debug and update the semantic function 2246*8c35d5eeSXin Li without having to recompile all clients of the macro. 2247*8c35d5eeSXin Li The semantic function appears in the stack trace 2248*8c35d5eeSXin Li which also helps debug client functions. 2249*8c35d5eeSXin Li The macro expansion is made shorter and 2250*8c35d5eeSXin Li each expansion shares more code with other expansions, 2251*8c35d5eeSXin Li which reduces memory pressure which in turn usually makes things faster. 2252*8c35d5eeSXin Li It also makes sense to write the semantic functions first, 2253*8c35d5eeSXin Li and write the macros last as syntactic sugar on top. 2254*8c35d5eeSXin Li You should use this style unless the macro is used 2255*8c35d5eeSXin Li in tight loops where performance matters; 2256*8c35d5eeSXin Li and even then, see our rules regarding optimization. 2257*8c35d5eeSXin Li </p> 2258*8c35d5eeSXin Li <p> 2259*8c35d5eeSXin Li Any functions (closures) created by the macro should be named, 2260*8c35d5eeSXin Li which can be done using <code>FLET</code>. 2261*8c35d5eeSXin Li 2262*8c35d5eeSXin Li This also allows you to declare the function to be of dynamic extent 2263*8c35d5eeSXin Li (if it is — and often it is; yet see below regarding 2264*8c35d5eeSXin Li <a href="#DYNAMIC-EXTENT">DYNAMIC-EXTENT</a>). 2265*8c35d5eeSXin Li </p> 2266*8c35d5eeSXin Li <p> 2267*8c35d5eeSXin Li If a macro call contains a form, 2268*8c35d5eeSXin Li and the macro expansion includes more than one copy of that form, 2269*8c35d5eeSXin Li the form can be evaluated more than once, 2270*8c35d5eeSXin Li and code it contains macro-expanded and compiled more than once. 2271*8c35d5eeSXin Li If someone uses the macro and calls it 2272*8c35d5eeSXin Li with a form that has side effects or that takes a long time to compute, 2273*8c35d5eeSXin Li the behavior will be undesirable 2274*8c35d5eeSXin Li (unless you're intentionally writing 2275*8c35d5eeSXin Li a control structure such as a loop). 2276*8c35d5eeSXin Li A convenient way to avoid this problem 2277*8c35d5eeSXin Li is to evaluate the form only once, 2278*8c35d5eeSXin Li and bind a (generated) variable to the result. 2279*8c35d5eeSXin Li There is a very useful macro called <code>ALEXANDRIA:ONCE-ONLY</code> 2280*8c35d5eeSXin Li that generates code to do this. 2281*8c35d5eeSXin Li See also <code>ALEXANDRIA:WITH-GENSYMS</code>, 2282*8c35d5eeSXin Li to make some temporary variables in the generated code. 2283*8c35d5eeSXin Li Note that if you follow our <code>CALL-WITH</code> style, 2284*8c35d5eeSXin Li you typically expand the code only once, as either 2285*8c35d5eeSXin Li an argument to the auxiliary function, or 2286*8c35d5eeSXin Li the body of a lambda passed as argument to it; 2287*8c35d5eeSXin Li you therefore avoid the above complexity. 2288*8c35d5eeSXin Li </p> 2289*8c35d5eeSXin Li <p> 2290*8c35d5eeSXin Li When you write a macro with a body, 2291*8c35d5eeSXin Li such as a <code>WITH-xxx</code> macro, 2292*8c35d5eeSXin Li even if there aren't any parameters, 2293*8c35d5eeSXin Li you should leave space for them anyway. 2294*8c35d5eeSXin Li For example, if you invent <code>WITH-LIGHTS-ON</code>, 2295*8c35d5eeSXin Li do not make the call to it look like 2296*8c35d5eeSXin Li <code>(defmacro with-lights-on (&body b) ...)</code>. 2297*8c35d5eeSXin Li Instead, do <code>(defmacro with-lights-on (() &body b) ...)</code>. 2298*8c35d5eeSXin Li That way, if parameters are needed in the future, 2299*8c35d5eeSXin Li you can add them without necessarily having to change 2300*8c35d5eeSXin Li all the uses of the macro. 2301*8c35d5eeSXin Li </p> 2302*8c35d5eeSXin Li </BODY> 2303*8c35d5eeSXin Li </STYLEPOINT> 2304*8c35d5eeSXin Li <STYLEPOINT title="EVAL-WHEN"> 2305*8c35d5eeSXin Li <SUMMARY> 2306*8c35d5eeSXin Li When using <code>EVAL-WHEN</code>, you should almost always use all of 2307*8c35d5eeSXin Li <code>(:compile-toplevel :load-toplevel :execute)</code>. 2308*8c35d5eeSXin Li </SUMMARY> 2309*8c35d5eeSXin Li <BODY> 2310*8c35d5eeSXin Li <p> 2311*8c35d5eeSXin Li Lisp evaluation happens at several times, 2312*8c35d5eeSXin Li some of them interleaved. 2313*8c35d5eeSXin Li Be aware of them when writing macros. 2314*8c35d5eeSXin Li <a href="https://fare.livejournal.com/146698.html">EVAL-WHEN considered harmful to your mental health</a>. 2315*8c35d5eeSXin Li </p> 2316*8c35d5eeSXin Li <p> 2317*8c35d5eeSXin Li In summary of the article linked above, 2318*8c35d5eeSXin Li unless you're doing truly advanced macrology, 2319*8c35d5eeSXin Li the only valid combination in an <code>EVAL-WHEN</code> 2320*8c35d5eeSXin Li is to include all of 2321*8c35d5eeSXin Li <code>(eval-when (:compile-toplevel :load-toplevel :execute) ...)</code> 2322*8c35d5eeSXin Li </p> 2323*8c35d5eeSXin Li <p> 2324*8c35d5eeSXin Li You must use 2325*8c35d5eeSXin Li <code>(eval-when (:compile-toplevel :load-toplevel :execute) ...)</code> 2326*8c35d5eeSXin Li whenever you define functions, types, classes, constants, variables, etc., 2327*8c35d5eeSXin Li that are going to be used in macros. 2328*8c35d5eeSXin Li </p> 2329*8c35d5eeSXin Li <p> 2330*8c35d5eeSXin Li It is usually an error to omit the <code>:execute</code>, 2331*8c35d5eeSXin Li because it prevents <code>LOAD</code>ing the source rather than the fasl. 2332*8c35d5eeSXin Li It is usually an error to omit the <code>:load-toplevel</code> 2333*8c35d5eeSXin Li (except to modify e.g. readtables and compile-time settings), 2334*8c35d5eeSXin Li because it prevents <code>LOAD</code>ing future files 2335*8c35d5eeSXin Li or interactively compiling code 2336*8c35d5eeSXin Li that depends on the effects that happen at compile-time, 2337*8c35d5eeSXin Li unless the current file was <code>COMPILE-FILE</code>d 2338*8c35d5eeSXin Li within the same Lisp session. 2339*8c35d5eeSXin Li </p> 2340*8c35d5eeSXin Li <p> 2341*8c35d5eeSXin Li Regarding variables, note that because macros may or may not 2342*8c35d5eeSXin Li be expanded in the same process that runs the expanded code, 2343*8c35d5eeSXin Li you must not depend on compile-time and runtime effects 2344*8c35d5eeSXin Li being either visible or invisible at the other time. 2345*8c35d5eeSXin Li There are still valid uses of variables in macros: 2346*8c35d5eeSXin Li </p> 2347*8c35d5eeSXin Li <ul> 2348*8c35d5eeSXin Li <li> 2349*8c35d5eeSXin Li Some variables may hold dictionaries 2350*8c35d5eeSXin Li for some new kind of definition and other meta-data. 2351*8c35d5eeSXin Li If such meta-data is to be visible at runtime and/or in other files, 2352*8c35d5eeSXin Li you must make sure that the macro expands into code that 2353*8c35d5eeSXin Li will register the definitions to those meta-data structures 2354*8c35d5eeSXin Li at load-time, 2355*8c35d5eeSXin Li in addition to effecting the registration at compile-time. 2356*8c35d5eeSXin Li Typically, your top-level definitions expand 2357*8c35d5eeSXin Li to code that does the registration. 2358*8c35d5eeSXin Li if your code doesn't expand at the top-level, 2359*8c35d5eeSXin Li you can sometimes use <code>LOAD-TIME-VALUE</code> for good effect. 2360*8c35d5eeSXin Li In extreme cases, you may have to use 2361*8c35d5eeSXin Li <code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code>. 2362*8c35d5eeSXin Li </li> 2363*8c35d5eeSXin Li <li> 2364*8c35d5eeSXin Li Some variables may hold temporary data 2365*8c35d5eeSXin Li that is only used at compile-time in the same file, 2366*8c35d5eeSXin Li and can be cleaned up at the end of the file's compilation. 2367*8c35d5eeSXin Li Predefined such variables would include <code>*readtable*</code> 2368*8c35d5eeSXin Li or compiler-internal variables holding 2369*8c35d5eeSXin Li the current optimization settings. 2370*8c35d5eeSXin Li You can often manage existing and new such variables using 2371*8c35d5eeSXin Li the <code>:AROUND-COMPILE</code> hooks of <code>ASDF</code>. 2372*8c35d5eeSXin Li </li> 2373*8c35d5eeSXin Li </ul> 2374*8c35d5eeSXin Li </BODY> 2375*8c35d5eeSXin Li </STYLEPOINT> 2376*8c35d5eeSXin Li <STYLEPOINT title="Read-time evaluation"> 2377*8c35d5eeSXin Li <SUMMARY> 2378*8c35d5eeSXin Li You should use <code>#.</code> sparingly, 2379*8c35d5eeSXin Li and you must avoid read-time side-effects. 2380*8c35d5eeSXin Li </SUMMARY> 2381*8c35d5eeSXin Li <BODY> 2382*8c35d5eeSXin Li <p> 2383*8c35d5eeSXin Li The <code>#.</code> standard read-macro 2384*8c35d5eeSXin Li will read one object, evaluate the object, and 2385*8c35d5eeSXin Li have the reader return the resulting value. 2386*8c35d5eeSXin Li </p> 2387*8c35d5eeSXin Li <p> 2388*8c35d5eeSXin Li You must not use it where other idioms will do, such as 2389*8c35d5eeSXin Li using <code>EVAL-WHEN</code> to evaluate side-effects at compile-time, 2390*8c35d5eeSXin Li using a regular macro to return an expression computed at compile-time, 2391*8c35d5eeSXin Li using <code>LOAD-TIME-VALUE</code> to compute it at load-time. 2392*8c35d5eeSXin Li </p> 2393*8c35d5eeSXin Li <p> 2394*8c35d5eeSXin Li Read-time evaluation is often used as a quick way 2395*8c35d5eeSXin Li to get something evaluated at compile time 2396*8c35d5eeSXin Li (actually "read time" but it amounts to the same thing). 2397*8c35d5eeSXin Li If you use this, the evaluation MUST NOT have any side effects 2398*8c35d5eeSXin Li and MUST NOT depend on any variable global state. 2399*8c35d5eeSXin Li The <code>#.</code> should be treated as a way 2400*8c35d5eeSXin Li to force "constant-folding" 2401*8c35d5eeSXin Li that a sufficiently-clever compiler 2402*8c35d5eeSXin Li could have figure out all by itself, 2403*8c35d5eeSXin Li when the compiler isn't sufficiently-clever 2404*8c35d5eeSXin Li and the difference matters. 2405*8c35d5eeSXin Li </p> 2406*8c35d5eeSXin Li <p> 2407*8c35d5eeSXin Li Another use of <code>#.</code> is to expand the equivalent of macros 2408*8c35d5eeSXin Li in places that are neither expressions nor (quasi)quotations, 2409*8c35d5eeSXin Li such as lambda-lists. However, if you find yourself using it a lot, 2410*8c35d5eeSXin Li it might be time to instead define macros to replace your consumers 2411*8c35d5eeSXin Li of lambda-lists with something that recognizes an extension. 2412*8c35d5eeSXin Li </p> 2413*8c35d5eeSXin Li <p> 2414*8c35d5eeSXin Li Whenever you are going to use <code>#.</code>, 2415*8c35d5eeSXin Li you should consider using <code>DEFCONSTANT</code> and its variants, 2416*8c35d5eeSXin Li possibly in an <code>EVAL-WHEN</code>, 2417*8c35d5eeSXin Li to give the value a name explaining what it means. 2418*8c35d5eeSXin Li </p> 2419*8c35d5eeSXin Li </BODY> 2420*8c35d5eeSXin Li </STYLEPOINT> 2421*8c35d5eeSXin Li <STYLEPOINT title="EVAL"> 2422*8c35d5eeSXin Li <SUMMARY> 2423*8c35d5eeSXin Li You must not use <code>EVAL</code> at runtime. 2424*8c35d5eeSXin Li </SUMMARY> 2425*8c35d5eeSXin Li <BODY> 2426*8c35d5eeSXin Li <p> 2427*8c35d5eeSXin Li Places where it is actually appropriate to use <code>EVAL</code> 2428*8c35d5eeSXin Li are so few and far between that you must consult with your reviewers; 2429*8c35d5eeSXin Li it's easily misused. 2430*8c35d5eeSXin Li </p> 2431*8c35d5eeSXin Li <p> 2432*8c35d5eeSXin Li If your code manipulates symbols at runtime 2433*8c35d5eeSXin Li and needs to get the value of a symbol, 2434*8c35d5eeSXin Li use <code>SYMBOL-VALUE</code>, not <code>EVAL</code>. 2435*8c35d5eeSXin Li </p> 2436*8c35d5eeSXin Li <p> 2437*8c35d5eeSXin Li Often, what you really need is to write a macro, 2438*8c35d5eeSXin Li not to use <code>EVAL</code>. 2439*8c35d5eeSXin Li </p> 2440*8c35d5eeSXin Li <p> 2441*8c35d5eeSXin Li You may be tempted to use <code>EVAL</code> as a shortcut 2442*8c35d5eeSXin Li to evaluating expressions in a safe subset of the language. 2443*8c35d5eeSXin Li But it often requires more scrutiny to properly check and sanitize 2444*8c35d5eeSXin Li all possible inputs to such use of <code>EVAL</code> 2445*8c35d5eeSXin Li than to build a special-purpose evaluator. 2446*8c35d5eeSXin Li You must not use <code>EVAL</code> in this way at runtime. 2447*8c35d5eeSXin Li </p> 2448*8c35d5eeSXin Li <p> 2449*8c35d5eeSXin Li Places where it is OK to use <code>EVAL</code> are: 2450*8c35d5eeSXin Li </p> 2451*8c35d5eeSXin Li <ul> 2452*8c35d5eeSXin Li <li> 2453*8c35d5eeSXin Li The implementation of an interactive development tool. 2454*8c35d5eeSXin Li </li> 2455*8c35d5eeSXin Li <li> 2456*8c35d5eeSXin Li The build infrastructure. 2457*8c35d5eeSXin Li </li> 2458*8c35d5eeSXin Li <li> 2459*8c35d5eeSXin Li Backdoors that are part of testing frameworks. 2460*8c35d5eeSXin Li (You MUST NOT have such backdoors in production code.) 2461*8c35d5eeSXin Li </li> 2462*8c35d5eeSXin Li <li> 2463*8c35d5eeSXin Li Macros that fold constants at compile-time. 2464*8c35d5eeSXin Li </li> 2465*8c35d5eeSXin Li <li> 2466*8c35d5eeSXin Li Macros that register definitions to meta-data structures; 2467*8c35d5eeSXin Li the registration form is sometimes evaluated at compile-time 2468*8c35d5eeSXin Li as well as included in the macro-expansion, 2469*8c35d5eeSXin Li so it is immediately available to other macros. 2470*8c35d5eeSXin Li </li> 2471*8c35d5eeSXin Li </ul> 2472*8c35d5eeSXin Li <p> 2473*8c35d5eeSXin Li Note that in the latter case, 2474*8c35d5eeSXin Li if the macro isn't going to be used at the top-level, 2475*8c35d5eeSXin Li it might not be possible to make these definitions available 2476*8c35d5eeSXin Li as part of the expansion. 2477*8c35d5eeSXin Li The same phenomenon may happen in a <code>DEFTYPE</code> expansion, 2478*8c35d5eeSXin Li or in helper functions used by macros. 2479*8c35d5eeSXin Li In these cases, you may actually have to use 2480*8c35d5eeSXin Li <code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code> in your macro. 2481*8c35d5eeSXin Li It will not only <code>EVAL</code> your definitions 2482*8c35d5eeSXin Li at macro-expansion time for immediate availability, 2483*8c35d5eeSXin Li it will also save the form aside, for inclusion in a 2484*8c35d5eeSXin Li <code>(ASDF-FINALIZERS:FINAL-FORMS)</code> 2485*8c35d5eeSXin Li that you need to include at the end of the file being compiled 2486*8c35d5eeSXin Li (or before the form is needed). 2487*8c35d5eeSXin Li This way, the side-effects are present when loading the fasl 2488*8c35d5eeSXin Li without having compiled it as well as while compiling it; 2489*8c35d5eeSXin Li in either case, the form is made available at load-time. 2490*8c35d5eeSXin Li <code>ASDF-FINALIZERS</code> ensures that the form is present, 2491*8c35d5eeSXin Li by throwing an error if you omit it. 2492*8c35d5eeSXin Li </p> 2493*8c35d5eeSXin Li </BODY> 2494*8c35d5eeSXin Li </STYLEPOINT> 2495*8c35d5eeSXin Li <STYLEPOINT title="INTERN and UNINTERN"> 2496*8c35d5eeSXin Li <SUMMARY> 2497*8c35d5eeSXin Li You must not use <code>INTERN</code> or <code>UNINTERN</code> at runtime. 2498*8c35d5eeSXin Li </SUMMARY> 2499*8c35d5eeSXin Li <BODY> 2500*8c35d5eeSXin Li <p> 2501*8c35d5eeSXin Li You must not use <code>INTERN</code> at runtime. 2502*8c35d5eeSXin Li Not only does it cons, 2503*8c35d5eeSXin Li it either creates a permanent symbol that won't be collected 2504*8c35d5eeSXin Li or gives access to internal symbols. 2505*8c35d5eeSXin Li This creates opportunities for memory leaks, denial of service attacks, 2506*8c35d5eeSXin Li unauthorized access to internals, clashes with other symbols. 2507*8c35d5eeSXin Li </p> 2508*8c35d5eeSXin Li <p> 2509*8c35d5eeSXin Li You must not <code>INTERN</code> a string 2510*8c35d5eeSXin Li just to compare it to a keyword; 2511*8c35d5eeSXin Li use <code>STRING=</code> or <code>STRING-EQUAL</code>. 2512*8c35d5eeSXin Li </p> 2513*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 2514*8c35d5eeSXin Li (member (intern str :keyword) $keys) ; Bad 2515*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 2516*8c35d5eeSXin Li <CODE_SNIPPET> 2517*8c35d5eeSXin Li (member str $keys :test #'string-equal) ; Better 2518*8c35d5eeSXin Li </CODE_SNIPPET> 2519*8c35d5eeSXin Li <p> 2520*8c35d5eeSXin Li You must not use <code>UNINTERN</code> at runtime. 2521*8c35d5eeSXin Li It can break code that relies on dynamic binding. 2522*8c35d5eeSXin Li It makes things harder to debug. 2523*8c35d5eeSXin Li You must not dynamically intern any new symbol, 2524*8c35d5eeSXin Li and therefore you need not dynamically unintern anything. 2525*8c35d5eeSXin Li </p> 2526*8c35d5eeSXin Li <p> 2527*8c35d5eeSXin Li You may of course use <code>INTERN</code> at compile-time, 2528*8c35d5eeSXin Li in the implementation of some macros. 2529*8c35d5eeSXin Li Even so, it is usually more appropriate 2530*8c35d5eeSXin Li to use abstractions on top of it, such as 2531*8c35d5eeSXin Li <code>ALEXANDRIA:SYMBOLICATE</code> or 2532*8c35d5eeSXin Li <code>ALEXANDRIA:FORMAT-SYMBOL</code> 2533*8c35d5eeSXin Li to create the symbols you need. 2534*8c35d5eeSXin Li </p> 2535*8c35d5eeSXin Li 2536*8c35d5eeSXin Li </BODY> 2537*8c35d5eeSXin Li </STYLEPOINT> 2538*8c35d5eeSXin Li</CATEGORY> 2539*8c35d5eeSXin Li 2540*8c35d5eeSXin Li<CATEGORY title="Data Representation"> 2541*8c35d5eeSXin Li <STYLEPOINT title="NIL: empty-list, false and I Don't Know"> 2542*8c35d5eeSXin Li <SUMMARY> 2543*8c35d5eeSXin Li Appropriately use or avoid using <code>NIL</code>. 2544*8c35d5eeSXin Li </SUMMARY> 2545*8c35d5eeSXin Li <BODY> 2546*8c35d5eeSXin Li <p> 2547*8c35d5eeSXin Li <code>NIL</code> can have several different interpretations: 2548*8c35d5eeSXin Li </p> 2549*8c35d5eeSXin Li <ul> 2550*8c35d5eeSXin Li <li> 2551*8c35d5eeSXin Li "False." 2552*8c35d5eeSXin Li In this case, use <code>NIL</code>. 2553*8c35d5eeSXin Li You should test for false <code>NIL</code> 2554*8c35d5eeSXin Li using the operator <code>NOT</code> or 2555*8c35d5eeSXin Li using the predicate function <code>NULL</code>. 2556*8c35d5eeSXin Li </li> 2557*8c35d5eeSXin Li <li> 2558*8c35d5eeSXin Li "Empty-list." 2559*8c35d5eeSXin Li In this case, use <code>'()</code>. 2560*8c35d5eeSXin Li (Be careful about quoting the empty-list when calling macros.) 2561*8c35d5eeSXin Li You should use <code>ENDP</code> to test for the empty list 2562*8c35d5eeSXin Li when the argument is known to be a proper list, 2563*8c35d5eeSXin Li or with <code>NULL</code> otherwise. 2564*8c35d5eeSXin Li </li> 2565*8c35d5eeSXin Li <li> 2566*8c35d5eeSXin Li A statement about some value being unspecified. 2567*8c35d5eeSXin Li In this case, you may use <code>NIL</code> 2568*8c35d5eeSXin Li if there is no risk of ambiguity anywhere in your code; 2569*8c35d5eeSXin Li otherwise you should use an explicit, descriptive symbol. 2570*8c35d5eeSXin Li </li> 2571*8c35d5eeSXin Li <li> 2572*8c35d5eeSXin Li A statement about some value being known not to exist. 2573*8c35d5eeSXin Li In this case, you should use an explicit, descriptive symbol 2574*8c35d5eeSXin Li instead of <code>NIL</code>. 2575*8c35d5eeSXin Li </li> 2576*8c35d5eeSXin Li </ul> 2577*8c35d5eeSXin Li <p> 2578*8c35d5eeSXin Li You must not introduce ambiguity in your data representations 2579*8c35d5eeSXin Li that will cause headaches for whoever has to debug code. 2580*8c35d5eeSXin Li If there is any risk of ambiguity, 2581*8c35d5eeSXin Li you should use an explicit, descriptive symbol or keyword 2582*8c35d5eeSXin Li for each case, 2583*8c35d5eeSXin Li instead of using <code>NIL</code> for either. 2584*8c35d5eeSXin Li If you do use <code>NIL</code>, 2585*8c35d5eeSXin Li you must make sure that the distinction is well documented. 2586*8c35d5eeSXin Li </p> 2587*8c35d5eeSXin Li <p> 2588*8c35d5eeSXin Li In many contexts, 2589*8c35d5eeSXin Li instead of representing "I don't know" as a particular value, 2590*8c35d5eeSXin Li you should instead use multiple values, 2591*8c35d5eeSXin Li one for the value that is known if any, 2592*8c35d5eeSXin Li and one to denote whether the value was known or found. 2593*8c35d5eeSXin Li </p> 2594*8c35d5eeSXin Li 2595*8c35d5eeSXin Li <p> 2596*8c35d5eeSXin Li When working with database classes, keep in mind that 2597*8c35d5eeSXin Li <code>NIL</code> need not always map to <code>'NULL'</code> 2598*8c35d5eeSXin Li (and vice-versa)! 2599*8c35d5eeSXin Li The needs of the database may differ from the needs of the Lisp. 2600*8c35d5eeSXin Li </p> 2601*8c35d5eeSXin Li </BODY> 2602*8c35d5eeSXin Li </STYLEPOINT> 2603*8c35d5eeSXin Li <STYLEPOINT title="Do not abuse lists"> 2604*8c35d5eeSXin Li <SUMMARY> 2605*8c35d5eeSXin Li You must select proper data representation. 2606*8c35d5eeSXin Li You must not abuse the <code>LIST</code> data structure. 2607*8c35d5eeSXin Li </SUMMARY> 2608*8c35d5eeSXin Li <BODY> 2609*8c35d5eeSXin Li <p> 2610*8c35d5eeSXin Li Even though back in 1958, LISP was short for "LISt Processing", 2611*8c35d5eeSXin Li its successor Common Lisp has been a modern programming language 2612*8c35d5eeSXin Li with modern data structures since the 1980s. 2613*8c35d5eeSXin Li You must use the proper data structures in your programs. 2614*8c35d5eeSXin Li </p> 2615*8c35d5eeSXin Li <p> 2616*8c35d5eeSXin Li You must not abuse the builtin (single-linked) <code>LIST</code> 2617*8c35d5eeSXin Li data structure where it is not appropriate, 2618*8c35d5eeSXin Li even though Common Lisp makes it especially easy to use it. 2619*8c35d5eeSXin Li </p> 2620*8c35d5eeSXin Li <p> 2621*8c35d5eeSXin Li You must only use lists 2622*8c35d5eeSXin Li when their performance characteristics 2623*8c35d5eeSXin Li is appropriate for the algorithm at hand: 2624*8c35d5eeSXin Li sequential iteration over the entire contents of the list. 2625*8c35d5eeSXin Li </p> 2626*8c35d5eeSXin Li <p> 2627*8c35d5eeSXin Li An exception where it is appropriate to use lists 2628*8c35d5eeSXin Li is when it is known in advance 2629*8c35d5eeSXin Li that the size of the list will remain very short 2630*8c35d5eeSXin Li (say, less than 16 elements). 2631*8c35d5eeSXin Li </p> 2632*8c35d5eeSXin Li <p> 2633*8c35d5eeSXin Li List data structures are often (but not always) 2634*8c35d5eeSXin Li appropriate for macros and functions used by macros at compile-time: 2635*8c35d5eeSXin Li indeed, not only is source code passed as lists in Common Lisp, 2636*8c35d5eeSXin Li but the macro-expansion and compilation processes 2637*8c35d5eeSXin Li will typically walk over the entire source code, sequentially, once. 2638*8c35d5eeSXin Li (Note that advanced macro systems don't directly use lists, but instead 2639*8c35d5eeSXin Li use abstract syntax objects that track source code location and scope; 2640*8c35d5eeSXin Li however there is no such advanced macro system 2641*8c35d5eeSXin Li in Common Lisp at this time.) 2642*8c35d5eeSXin Li </p> 2643*8c35d5eeSXin Li <p> 2644*8c35d5eeSXin Li Another exception where it is appropriate to use lists is 2645*8c35d5eeSXin Li for introducing literal constants 2646*8c35d5eeSXin Li that will be transformed into more appropriate data structures 2647*8c35d5eeSXin Li at compile-time or load-time. 2648*8c35d5eeSXin Li It is a good to have a function with a relatively short name 2649*8c35d5eeSXin Li to build your program's data structures from such literals. 2650*8c35d5eeSXin Li </p> 2651*8c35d5eeSXin Li <p> 2652*8c35d5eeSXin Li In the many cases when lists are not the appropriate data structure, 2653*8c35d5eeSXin Li various libraries such as 2654*8c35d5eeSXin Li <a href="http://cliki.net/cl-containers">cl-containers</a> or 2655*8c35d5eeSXin Li <a href="http://cliki.net/lisp-interface-library">lisp-interface-library</a> 2656*8c35d5eeSXin Li provide plenty of different data structures 2657*8c35d5eeSXin Li that should fulfill all the basic needs of your programs. 2658*8c35d5eeSXin Li If the existing libraries are not satisfactory, see above about 2659*8c35d5eeSXin Li <a href="#Using_Libraries">Using Libraries</a> and 2660*8c35d5eeSXin Li <a href="#Open-Sourcing_Code">Open-Sourcing Code</a>. 2661*8c35d5eeSXin Li </p> 2662*8c35d5eeSXin Li </BODY> 2663*8c35d5eeSXin Li </STYLEPOINT> 2664*8c35d5eeSXin Li <STYLEPOINT title="Lists vs. structures vs. multiple values"> 2665*8c35d5eeSXin Li <SUMMARY> 2666*8c35d5eeSXin Li You should use the appropriate representation for product types. 2667*8c35d5eeSXin Li </SUMMARY> 2668*8c35d5eeSXin Li <BODY> 2669*8c35d5eeSXin Li <p> 2670*8c35d5eeSXin Li You should avoid using a list as anything 2671*8c35d5eeSXin Li besides a container of elements of like type. 2672*8c35d5eeSXin Li You must not use a list as method of passing 2673*8c35d5eeSXin Li multiple separate values of different types 2674*8c35d5eeSXin Li in and out of function calls. 2675*8c35d5eeSXin Li Sometimes it is convenient to use a list 2676*8c35d5eeSXin Li as a little ad hoc structure, 2677*8c35d5eeSXin Li i.e. "the first element of the list is a FOO, and the second is a BAR", 2678*8c35d5eeSXin Li but this should be used minimally 2679*8c35d5eeSXin Li since it gets harder to remember the little convention. 2680*8c35d5eeSXin Li You must only use a list that way 2681*8c35d5eeSXin Li when destructuring the list of arguments from a function, 2682*8c35d5eeSXin Li or creating a list of arguments 2683*8c35d5eeSXin Li to which to <code>APPLY</code> a function. 2684*8c35d5eeSXin Li </p> 2685*8c35d5eeSXin Li <p> 2686*8c35d5eeSXin Li The proper way to pass around an object 2687*8c35d5eeSXin Li comprising several values of heterogeneous types 2688*8c35d5eeSXin Li is to use a structure as defined by <code>DEFSTRUCT</code> 2689*8c35d5eeSXin Li or <code>DEFCLASS</code>. 2690*8c35d5eeSXin Li </p> 2691*8c35d5eeSXin Li <p> 2692*8c35d5eeSXin Li You should use multiple values only 2693*8c35d5eeSXin Li when function returns a small number of values 2694*8c35d5eeSXin Li that are meant to be destructured immediately by the caller, 2695*8c35d5eeSXin Li rather than passed together as arguments to further functions. 2696*8c35d5eeSXin Li </p> 2697*8c35d5eeSXin Li <p> 2698*8c35d5eeSXin Li You should not return a condition object 2699*8c35d5eeSXin Li as one of a set of multiple values. 2700*8c35d5eeSXin Li Instead, you should signal the condition to denote an unusual outcome. 2701*8c35d5eeSXin Li </p> 2702*8c35d5eeSXin Li <p> 2703*8c35d5eeSXin Li You should signal a condition to denote an unusual outcome, 2704*8c35d5eeSXin Li rather than relying on a special return type. 2705*8c35d5eeSXin Li </p> 2706*8c35d5eeSXin Li </BODY> 2707*8c35d5eeSXin Li </STYLEPOINT> 2708*8c35d5eeSXin Li <STYLEPOINT title="Lists vs. Pairs"> 2709*8c35d5eeSXin Li <SUMMARY> 2710*8c35d5eeSXin Li Use the appropriate functions when manipulating lists. 2711*8c35d5eeSXin Li </SUMMARY> 2712*8c35d5eeSXin Li <BODY> 2713*8c35d5eeSXin Li <p> 2714*8c35d5eeSXin Li Use <code>FIRST</code> to access the first element of a list, 2715*8c35d5eeSXin Li <code>SECOND</code> to access the second element, etc. 2716*8c35d5eeSXin Li Use <code>REST</code> to access the tail of a list. 2717*8c35d5eeSXin Li Use <code>ENDP</code> to test for the end of the list. 2718*8c35d5eeSXin Li </p> 2719*8c35d5eeSXin Li <p> 2720*8c35d5eeSXin Li Use <code>CAR</code> and <code>CDR</code> 2721*8c35d5eeSXin Li when the cons cell is not being used to implement a proper list 2722*8c35d5eeSXin Li and is instead being treated as a pair of more general objects. 2723*8c35d5eeSXin Li Use <code>NULL</code> to test for <code>NIL</code> in this context. 2724*8c35d5eeSXin Li </p> 2725*8c35d5eeSXin Li <p> 2726*8c35d5eeSXin Li The latter case should be rare outside of alists, 2727*8c35d5eeSXin Li since you should be using structures and classes where they apply, 2728*8c35d5eeSXin Li and data structure libraries when you want trees. 2729*8c35d5eeSXin Li </p> 2730*8c35d5eeSXin Li <p> 2731*8c35d5eeSXin Li Exceptionally, you may use <code>CDADR</code> and other variants 2732*8c35d5eeSXin Li on lists when manually destructuring them, 2733*8c35d5eeSXin Li instead of using a combination of several list accessor functions. 2734*8c35d5eeSXin Li In this context, using <code>CAR</code> and <code>CDR</code> 2735*8c35d5eeSXin Li instead of <code>FIRST</code> and <code>REST</code> also makes sense. 2736*8c35d5eeSXin Li However, keep in mind that it might be more appropriate in such cases 2737*8c35d5eeSXin Li to use higher-level constructs such as 2738*8c35d5eeSXin Li <code>DESTRUCTURING-BIND</code> or <code>OPTIMA:MATCH</code>. 2739*8c35d5eeSXin Li </p> 2740*8c35d5eeSXin Li </BODY> 2741*8c35d5eeSXin Li </STYLEPOINT> 2742*8c35d5eeSXin Li <STYLEPOINT title="Lists vs. Arrays"> 2743*8c35d5eeSXin Li <SUMMARY> 2744*8c35d5eeSXin Li You should use arrays rather than lists where random access matters. 2745*8c35d5eeSXin Li </SUMMARY> 2746*8c35d5eeSXin Li <BODY> 2747*8c35d5eeSXin Li <p> 2748*8c35d5eeSXin Li <code>ELT</code> has <i>O(n)</i> behavior when used on lists. 2749*8c35d5eeSXin Li If you are to use random element access on an object, 2750*8c35d5eeSXin Li use arrays and <code>AREF</code> instead. 2751*8c35d5eeSXin Li </p> 2752*8c35d5eeSXin Li <p> 2753*8c35d5eeSXin Li The exception is for code outside the critical path 2754*8c35d5eeSXin Li where the list is known to be small anyway. 2755*8c35d5eeSXin Li </p> 2756*8c35d5eeSXin Li </BODY> 2757*8c35d5eeSXin Li </STYLEPOINT> 2758*8c35d5eeSXin Li <STYLEPOINT title="Lists vs. Sets"> 2759*8c35d5eeSXin Li <SUMMARY> 2760*8c35d5eeSXin Li You should only use lists as sets for very small lists. 2761*8c35d5eeSXin Li </SUMMARY> 2762*8c35d5eeSXin Li <BODY> 2763*8c35d5eeSXin Li <p> 2764*8c35d5eeSXin Li Using lists as representations of sets is a bad idea 2765*8c35d5eeSXin Li unless you know the lists will be small, 2766*8c35d5eeSXin Li for accessors are <i>O(n)</i> instead of <i>O(log n)</i>. 2767*8c35d5eeSXin Li For arbitrary big sets, use balanced binary trees, 2768*8c35d5eeSXin Li for instance using <code>lisp-interface-library</code>. 2769*8c35d5eeSXin Li </p> 2770*8c35d5eeSXin Li <p> 2771*8c35d5eeSXin Li If you still use lists as sets, 2772*8c35d5eeSXin Li you should not <code>UNION</code> lists just to search them. 2773*8c35d5eeSXin Li </p> 2774*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 2775*8c35d5eeSXin Li (member foo (union list-1 list-2)) ; Bad 2776*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 2777*8c35d5eeSXin Li <CODE_SNIPPET> 2778*8c35d5eeSXin Li (or (member foo list-1) (member foo list-2)) ; Better 2779*8c35d5eeSXin Li </CODE_SNIPPET> 2780*8c35d5eeSXin Li <p> 2781*8c35d5eeSXin Li Indeed, <code>UNION</code> not only conses unnecessarily, 2782*8c35d5eeSXin Li but it can be <i>O(n^2)</i> on some implementations, 2783*8c35d5eeSXin Li and is rather slow even when it's <i>O(n)</i>. 2784*8c35d5eeSXin Li </p> 2785*8c35d5eeSXin Li </BODY> 2786*8c35d5eeSXin Li </STYLEPOINT> 2787*8c35d5eeSXin Li</CATEGORY> 2788*8c35d5eeSXin Li 2789*8c35d5eeSXin Li<CATEGORY title="Proper Forms"> 2790*8c35d5eeSXin Li <p> 2791*8c35d5eeSXin Li You must follow the proper usage regarding 2792*8c35d5eeSXin Li well-known functions, macros and special forms. 2793*8c35d5eeSXin Li </p> 2794*8c35d5eeSXin Li <STYLEPOINT title="Defining Constants"> 2795*8c35d5eeSXin Li <SUMMARY> 2796*8c35d5eeSXin Li You must use proper defining forms for constant values. 2797*8c35d5eeSXin Li </SUMMARY> 2798*8c35d5eeSXin Li <BODY> 2799*8c35d5eeSXin Li <p> 2800*8c35d5eeSXin Li The Lisp system we primarily use, SBCL, is very picky and 2801*8c35d5eeSXin Li signals a condition whenever a constant is redefined to a value not 2802*8c35d5eeSXin Li <code>EQL</code> to its previous setting. 2803*8c35d5eeSXin Li You must not use <code>DEFCONSTANT</code> 2804*8c35d5eeSXin Li when defining variables that are not 2805*8c35d5eeSXin Li numbers, characters, or symbols (including booleans and keywords). 2806*8c35d5eeSXin Li Instead, consistently use whichever alternative 2807*8c35d5eeSXin Li is recommended for your project. 2808*8c35d5eeSXin Li </p> 2809*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 2810*8c35d5eeSXin Li ;; Bad 2811*8c35d5eeSXin Li (defconstant +google-url+ "https://www.google.com/") 2812*8c35d5eeSXin Li (defconstant +valid-colors+ '(red green blue)) 2813*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 2814*8c35d5eeSXin Li 2815*8c35d5eeSXin Li 2816*8c35d5eeSXin Li 2817*8c35d5eeSXin Li 2818*8c35d5eeSXin Li <p> 2819*8c35d5eeSXin Li Open-Source libraries may use 2820*8c35d5eeSXin Li <code>ALEXANDRIA:DEFINE-CONSTANT</code> 2821*8c35d5eeSXin Li for constants other than numbers, characters and symbols 2822*8c35d5eeSXin Li (including booleans and keywords). 2823*8c35d5eeSXin Li You may use the <code>:TEST</code> keyword argument 2824*8c35d5eeSXin Li to specify an equality predicate. 2825*8c35d5eeSXin Li </p> 2826*8c35d5eeSXin Li <CODE_SNIPPET> 2827*8c35d5eeSXin Li ;; Better, for Open-Source code: 2828*8c35d5eeSXin Li (define-constant +google-url+ "https://www.google.com/" :test #'string=) 2829*8c35d5eeSXin Li (define-constant +valid-colors+ '(red green blue)) 2830*8c35d5eeSXin Li </CODE_SNIPPET> 2831*8c35d5eeSXin Li <p> 2832*8c35d5eeSXin Li Note that with optimizing implementations, such as SBCL or CMUCL, 2833*8c35d5eeSXin Li defining constants this way precludes any later redefinition 2834*8c35d5eeSXin Li short of <code>UNINTERN</code>ing the symbol 2835*8c35d5eeSXin Li and recompiling all its clients. 2836*8c35d5eeSXin Li This may make it "interesting" to debug things at the REPL 2837*8c35d5eeSXin Li or to deploy live code upgrades. 2838*8c35d5eeSXin Li If there is a chance that your "constants" are not going to be constant 2839*8c35d5eeSXin Li over the lifetime of your server processes 2840*8c35d5eeSXin Li after taking into consideration scheduled and unscheduled code patches, 2841*8c35d5eeSXin Li you should consider using 2842*8c35d5eeSXin Li <code>DEFPARAMETER</code> or <code>DEFVAR</code> instead, 2843*8c35d5eeSXin Li or possibly a variant of <code>DEFINE-CONSTANT</code> 2844*8c35d5eeSXin Li that builds upon some future library implementing global lexicals 2845*8c35d5eeSXin Li rather than <code>DEFCONSTANT</code>. 2846*8c35d5eeSXin Li You may keep the <code>+plus+</code> convention in these cases 2847*8c35d5eeSXin Li to document the intent of the parameter as a constant. 2848*8c35d5eeSXin Li </p> 2849*8c35d5eeSXin Li <p> 2850*8c35d5eeSXin Li Also note that <code>LOAD-TIME-VALUE</code> may help you 2851*8c35d5eeSXin Li avoid the need for defined constants. 2852*8c35d5eeSXin Li </p> 2853*8c35d5eeSXin Li </BODY> 2854*8c35d5eeSXin Li </STYLEPOINT> 2855*8c35d5eeSXin Li <STYLEPOINT title="Defining Functions"> 2856*8c35d5eeSXin Li <SUMMARY> 2857*8c35d5eeSXin Li You should make proper use of 2858*8c35d5eeSXin Li <code>&OPTIONAL</code> and 2859*8c35d5eeSXin Li <code>&KEY</code> arguments. 2860*8c35d5eeSXin Li You should not use <code>&AUX</code> arguments. 2861*8c35d5eeSXin Li </SUMMARY> 2862*8c35d5eeSXin Li <BODY> 2863*8c35d5eeSXin Li <p> 2864*8c35d5eeSXin Li You should avoid using <code>&ALLOW-OTHER-KEYS</code>, 2865*8c35d5eeSXin Li since it blurs the contract of a function. 2866*8c35d5eeSXin Li Almost any real function (generic or not) allows a certain 2867*8c35d5eeSXin Li fixed set of keywords, as far as its caller is concerned, 2868*8c35d5eeSXin Li and those are part of its contract. 2869*8c35d5eeSXin Li If you are implementing a method of a generic function, 2870*8c35d5eeSXin Li and it does not need to know 2871*8c35d5eeSXin Li the values of some of the keyword arguments, 2872*8c35d5eeSXin Li you should explicitly <code>(DECLARE (IGNORE ...))</code> 2873*8c35d5eeSXin Li all the arguments that you are not using. 2874*8c35d5eeSXin Li You must not use <code>&ALLOW-OTHER-KEYS</code> 2875*8c35d5eeSXin Li unless you explicitly want to disable checking of allowed keys 2876*8c35d5eeSXin Li for all methods when invoking the generic function on arguments 2877*8c35d5eeSXin Li that match this particular method. 2878*8c35d5eeSXin Li Note that the contract of a generic function belongs in 2879*8c35d5eeSXin Li the <code>DEFGENERIC</code>, not in the <code>DEFMETHOD</code> 2880*8c35d5eeSXin Li which is basically an "implementation detail" of the generic function 2881*8c35d5eeSXin Li as far as the caller of the generic is concerned. 2882*8c35d5eeSXin Li </p> 2883*8c35d5eeSXin Li <p> 2884*8c35d5eeSXin Li A case where <code>&ALLOW-OTHER-KEYS</code> is appropriate 2885*8c35d5eeSXin Li is when you write a wrapper function to other some other functions 2886*8c35d5eeSXin Li that may vary (within the computation or during development), 2887*8c35d5eeSXin Li and pass around a plist as a <code>&REST</code> argument. 2888*8c35d5eeSXin Li </p> 2889*8c35d5eeSXin Li <p> 2890*8c35d5eeSXin Li You should avoid using <code>&AUX</code> arguments. 2891*8c35d5eeSXin Li </p> 2892*8c35d5eeSXin Li <p> 2893*8c35d5eeSXin Li You should avoid having both <code>&OPTIONAL</code> 2894*8c35d5eeSXin Li and <code>&KEY</code> arguments, 2895*8c35d5eeSXin Li unless it never makes sense to specify keyword arguments 2896*8c35d5eeSXin Li when the optional arguments are not all specified. 2897*8c35d5eeSXin Li You must not have non-<code>NIL</code> defaults 2898*8c35d5eeSXin Li to your <code>&OPTIONAL</code> arguments 2899*8c35d5eeSXin Li when your function has both <code>&OPTIONAL</code> 2900*8c35d5eeSXin Li and <code>&KEY</code> arguments. 2901*8c35d5eeSXin Li </p> 2902*8c35d5eeSXin Li <p> 2903*8c35d5eeSXin Li For maximum portability of a library, it is good form 2904*8c35d5eeSXin Li that <code>DEFMETHOD</code> definitions should 2905*8c35d5eeSXin Li <code>(DECLARE (IGNORABLE ...))</code> 2906*8c35d5eeSXin Li all the required arguments that they are not using. 2907*8c35d5eeSXin Li Indeed, some implementations will issue a warning 2908*8c35d5eeSXin Li if you <code>(DECLARE (IGNORE ...))</code> those arguments, 2909*8c35d5eeSXin Li whereas other implementations will issue a warning 2910*8c35d5eeSXin Li if you fail to <code>(DECLARE (IGNORE ...))</code> them. 2911*8c35d5eeSXin Li <code>(DECLARE (IGNORABLE ...))</code> works on all implementations. 2912*8c35d5eeSXin Li </p> 2913*8c35d5eeSXin Li <p> 2914*8c35d5eeSXin Li You should avoid excessive nesting of binding forms inside a function. 2915*8c35d5eeSXin Li If your function ends up with massive nesting, 2916*8c35d5eeSXin Li you should probably break it up into several functions or macros. 2917*8c35d5eeSXin Li If it is really a single conceptual unit, 2918*8c35d5eeSXin Li consider using a macro such as <code>FARE-UTILS:NEST</code> 2919*8c35d5eeSXin Li to at least reduce the amount of indentation required. 2920*8c35d5eeSXin Li It is bad form to use <code>NEST</code> in typical short functions 2921*8c35d5eeSXin Li with 4 or fewer levels of nesting, 2922*8c35d5eeSXin Li but also bad form not to use it in the exceptional long functions 2923*8c35d5eeSXin Li with 10 or more levels of nesting. 2924*8c35d5eeSXin Li Use your judgment and consult your reviewers. 2925*8c35d5eeSXin Li </p> 2926*8c35d5eeSXin Li 2927*8c35d5eeSXin Li </BODY> 2928*8c35d5eeSXin Li </STYLEPOINT> 2929*8c35d5eeSXin Li <STYLEPOINT title="Conditional Expressions"> 2930*8c35d5eeSXin Li <SUMMARY> 2931*8c35d5eeSXin Li Use the appropriate conditional form. 2932*8c35d5eeSXin Li </SUMMARY> 2933*8c35d5eeSXin Li <BODY> 2934*8c35d5eeSXin Li <p> 2935*8c35d5eeSXin Li Use <code>WHEN</code> and <code>UNLESS</code> 2936*8c35d5eeSXin Li when there is only one alternative. 2937*8c35d5eeSXin Li Use <code>IF</code> when there are two alternatives 2938*8c35d5eeSXin Li and <code>COND</code> when there are several. 2939*8c35d5eeSXin Li </p> 2940*8c35d5eeSXin Li <p> 2941*8c35d5eeSXin Li However, don't use <code>PROGN</code> for an <code>IF</code> clause 2942*8c35d5eeSXin Li — use <code>COND</code>, <code>WHEN</code>, or <code>UNLESS</code>. 2943*8c35d5eeSXin Li </p> 2944*8c35d5eeSXin Li <p> 2945*8c35d5eeSXin Li Note that in Common Lisp, 2946*8c35d5eeSXin Li <code>WHEN</code> and <code>UNLESS</code> return <code>NIL</code> 2947*8c35d5eeSXin Li when the condition is not met. 2948*8c35d5eeSXin Li You may take advantage of it. 2949*8c35d5eeSXin Li Nevertheless, you may use an <code>IF</code> 2950*8c35d5eeSXin Li to explicitly return <code>NIL</code> 2951*8c35d5eeSXin Li if you have a specific reason to insist on the return value. 2952*8c35d5eeSXin Li You may similarly include a fall-through clause <code>(t nil)</code> 2953*8c35d5eeSXin Li as the last in your <cond>COND</cond>, 2954*8c35d5eeSXin Li or <code>(otherwise nil)</code> as the last in your <cond>CASE</cond>, 2955*8c35d5eeSXin Li to insist on the fact that the value returned by the conditional matters 2956*8c35d5eeSXin Li and that such a case is going to be used. 2957*8c35d5eeSXin Li You should omit the fall-through clause 2958*8c35d5eeSXin Li when the conditional is used for side-effects. 2959*8c35d5eeSXin Li </p> 2960*8c35d5eeSXin Li <p> 2961*8c35d5eeSXin Li You should prefer <code>AND</code> and <code>OR</code> 2962*8c35d5eeSXin Li when it leads to more concise code than using 2963*8c35d5eeSXin Li <code>IF</code>, <code>COND</code>, 2964*8c35d5eeSXin Li <code>WHEN</code> or <code>UNLESS</code>, 2965*8c35d5eeSXin Li and there are no side-effects involved. 2966*8c35d5eeSXin Li You may also use an <code>ERROR</code> 2967*8c35d5eeSXin Li as a side-effect in the final clause of an <code>OR</code>. 2968*8c35d5eeSXin Li </p> 2969*8c35d5eeSXin Li <p> 2970*8c35d5eeSXin Li You should only use <code>CASE</code> and <code>ECASE</code> 2971*8c35d5eeSXin Li to compare numbers, characters or symbols 2972*8c35d5eeSXin Li (including booleans and keywords). 2973*8c35d5eeSXin Li Indeed, <code>CASE</code> uses <code>EQL</code> for comparisons, 2974*8c35d5eeSXin Li so strings, pathnames and structures may not compare the way you expect, 2975*8c35d5eeSXin Li and <code>1</code> will differ from <code>1.0</code>. 2976*8c35d5eeSXin Li </p> 2977*8c35d5eeSXin Li <p> 2978*8c35d5eeSXin Li You should use <code>ECASE</code> and <code>ETYPECASE</code> 2979*8c35d5eeSXin Li in preference to <code>CASE</code> and <code>TYPECASE</code>. 2980*8c35d5eeSXin Li It is better to catch erroneous values early. 2981*8c35d5eeSXin Li </p> 2982*8c35d5eeSXin Li <p> 2983*8c35d5eeSXin Li You should not use <code>CCASE</code> or <code>CTYPECASE</code> at all. 2984*8c35d5eeSXin Li At least, you should not use them in server processes, 2985*8c35d5eeSXin Li unless you have quite robust error handling infrastructure 2986*8c35d5eeSXin Li and make sure not to leak sensitive data this way. 2987*8c35d5eeSXin Li These are meant for interactive use, 2988*8c35d5eeSXin Li and can cause interesting damage 2989*8c35d5eeSXin Li if they cause data or control to leak to attackers. 2990*8c35d5eeSXin Li </p> 2991*8c35d5eeSXin Li <p> 2992*8c35d5eeSXin Li You must not use gratuitous single quotes in <code>CASE</code> forms. 2993*8c35d5eeSXin Li This is a common error: 2994*8c35d5eeSXin Li </p> 2995*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 2996*8c35d5eeSXin Li (case x ; Bad: silently returns NIL on mismatch 2997*8c35d5eeSXin Li ('bar :bar) ; Bad: catches QUOTE 2998*8c35d5eeSXin Li ('baz :baz)) ; Bad: also would catch QUOTE 2999*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 3000*8c35d5eeSXin Li <CODE_SNIPPET> 3001*8c35d5eeSXin Li (ecase x ; Better: will error on mismatch 3002*8c35d5eeSXin Li ((bar) :bar) ; Better: won't match QUOTE 3003*8c35d5eeSXin Li ((baz) :baz)) ; Better: same reason 3004*8c35d5eeSXin Li </CODE_SNIPPET> 3005*8c35d5eeSXin Li <p> 3006*8c35d5eeSXin Li <code>'BAR</code> there is <code>(QUOTE BAR)</code>, 3007*8c35d5eeSXin Li meaning this leg of the case will be executed 3008*8c35d5eeSXin Li if <code>X</code> is <code>QUOTE</code>... 3009*8c35d5eeSXin Li and ditto for the second leg 3010*8c35d5eeSXin Li (though <code>QUOTE</code> will be caught by the first clause). 3011*8c35d5eeSXin Li This is unlikely to be what you really want. 3012*8c35d5eeSXin Li </p> 3013*8c35d5eeSXin Li <p> 3014*8c35d5eeSXin Li In <code>CASE</code> forms, 3015*8c35d5eeSXin Li you must use <code>otherwise</code> instead of <code>t</code> 3016*8c35d5eeSXin Li when you mean "execute this clause if the others fail". 3017*8c35d5eeSXin Li You must use <code>((t) ...)</code> 3018*8c35d5eeSXin Li when you mean "match the symbol T" rather than "match anything". 3019*8c35d5eeSXin Li You must also use <code>((nil) ...)</code> 3020*8c35d5eeSXin Li when you mean "match the symbol NIL" rather than "match nothing". 3021*8c35d5eeSXin Li </p> 3022*8c35d5eeSXin Li <p> 3023*8c35d5eeSXin Li Therefore, if you want to map booleans <code>NIL</code> and <code>T</code> 3024*8c35d5eeSXin Li to respective symbols <code>:BAR</code> and <code>:QUUX</code>, 3025*8c35d5eeSXin Li you should avoid the former way and do it the latter way: 3026*8c35d5eeSXin Li </p> 3027*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 3028*8c35d5eeSXin Li (ecase x ; Bad: has no actual error case! 3029*8c35d5eeSXin Li (nil :bar)) ; Bad: matches nothing 3030*8c35d5eeSXin Li (t :quux)) ; Bad: matches anything 3031*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 3032*8c35d5eeSXin Li <CODE_SNIPPET> 3033*8c35d5eeSXin Li (ecase x ; Better: will actually catch non-booleans 3034*8c35d5eeSXin Li ((nil) :bar)) ; Better: matches NIL 3035*8c35d5eeSXin Li ((t) :quux)) ; Better: matches T 3036*8c35d5eeSXin Li </CODE_SNIPPET> 3037*8c35d5eeSXin Li </BODY> 3038*8c35d5eeSXin Li </STYLEPOINT> 3039*8c35d5eeSXin Li <STYLEPOINT title="Identity, Equality and Comparisons"> 3040*8c35d5eeSXin Li <SUMMARY> 3041*8c35d5eeSXin Li You should the appropriate predicates when comparing objects. 3042*8c35d5eeSXin Li </SUMMARY> 3043*8c35d5eeSXin Li <BODY> 3044*8c35d5eeSXin Li <p> 3045*8c35d5eeSXin Li Lisp provides four general equality predicates: 3046*8c35d5eeSXin Li <code>EQ</code>, <code>EQL</code>, <code>EQUAL</code>, 3047*8c35d5eeSXin Li and <code>EQUALP</code>, 3048*8c35d5eeSXin Li which subtly vary in semantics. 3049*8c35d5eeSXin Li Additionally, Lisp provides the type-specific predicates 3050*8c35d5eeSXin Li <code>=</code>, <code>CHAR=</code>, <code>CHAR-EQUAL</code>, 3051*8c35d5eeSXin Li <code>STRING=</code>, and <code>STRING-EQUAL</code>. 3052*8c35d5eeSXin Li Know the distinction! 3053*8c35d5eeSXin Li </p> 3054*8c35d5eeSXin Li <p> 3055*8c35d5eeSXin Li You should use <code>EQL</code> to compare objects and symbols 3056*8c35d5eeSXin Li for <em>identity</em>. 3057*8c35d5eeSXin Li </p> 3058*8c35d5eeSXin Li <p> 3059*8c35d5eeSXin Li You must not use <code>EQ</code> to compare numbers or characters. 3060*8c35d5eeSXin Li Two numbers or characters that are <code>EQL</code> 3061*8c35d5eeSXin Li are not required by Common Lisp to be <code>EQ</code>. 3062*8c35d5eeSXin Li </p> 3063*8c35d5eeSXin Li <p> 3064*8c35d5eeSXin Li When choosing between <code>EQ</code> and <code>EQL</code>, 3065*8c35d5eeSXin Li you should use <code>EQL</code> unless you are writing 3066*8c35d5eeSXin Li performance-critical low-level code. 3067*8c35d5eeSXin Li <code>EQL</code> reduces the opportunity 3068*8c35d5eeSXin Li for a class of embarrassing errors 3069*8c35d5eeSXin Li (i.e. if numbers or characters are ever compared). 3070*8c35d5eeSXin Li There may a tiny performance cost relative to <code>EQ</code>, 3071*8c35d5eeSXin Li although under SBCL, it often compiles away entirely. 3072*8c35d5eeSXin Li <code>EQ</code> is equivalent to <code>EQL</code> and type declarations, 3073*8c35d5eeSXin Li and use of it for optimization should be treated just like 3074*8c35d5eeSXin Li any such <a href="#Unsafe_Operations">unsafe operations</a>. 3075*8c35d5eeSXin Li </p> 3076*8c35d5eeSXin Li <p> 3077*8c35d5eeSXin Li You should use <code>CHAR=</code> 3078*8c35d5eeSXin Li for case-dependent character comparisons, 3079*8c35d5eeSXin Li and <code>CHAR-EQUAL</code> for case-ignoring character comparisons. 3080*8c35d5eeSXin Li </p> 3081*8c35d5eeSXin Li <p> 3082*8c35d5eeSXin Li You should use <code>STRING=</code> 3083*8c35d5eeSXin Li for case-dependent string comparisons, 3084*8c35d5eeSXin Li and <code>STRING-EQUAL</code> for case-ignoring string comparisons. 3085*8c35d5eeSXin Li </p> 3086*8c35d5eeSXin Li <p> 3087*8c35d5eeSXin Li A common mistake when using <code>SEARCH</code> on strings 3088*8c35d5eeSXin Li is to provide <code>STRING=</code> or <code>STRING-EQUAL</code> 3089*8c35d5eeSXin Li as the <code>:TEST</code> function. 3090*8c35d5eeSXin Li The <code>:TEST</code> function 3091*8c35d5eeSXin Li is given two sequence elements to compare. 3092*8c35d5eeSXin Li If the sequences are strings, 3093*8c35d5eeSXin Li the <code>:TEST</code> function is called on two characters, 3094*8c35d5eeSXin Li so the correct tests are <code>CHAR=</code> or <code>CHAR-EQUAL</code>. 3095*8c35d5eeSXin Li If you use <code>STRING=</code> or <code>STRING-EQUAL</code>, 3096*8c35d5eeSXin Li the result is what you expect, 3097*8c35d5eeSXin Li but in some Lisp implementations it's much slower. 3098*8c35d5eeSXin Li CCL (at least as of 8/2008) 3099*8c35d5eeSXin Li creates a one-character string upon each comparison, for example, 3100*8c35d5eeSXin Li which is very expensive. 3101*8c35d5eeSXin Li </p> 3102*8c35d5eeSXin Li <p> 3103*8c35d5eeSXin Li Also, you should use <code>:START</code> and <code>:END</code> arguments 3104*8c35d5eeSXin Li to <code>STRING=</code> or <code>STRING-EQUAL</code> 3105*8c35d5eeSXin Li instead of using <code>SUBSEQ</code>; 3106*8c35d5eeSXin Li e.g. <code>(string-equal (subseq s1 2 6) s2)</code> should instead be 3107*8c35d5eeSXin Li <code>(string-equal s1 s2 :start1 2 :end1 6)</code> 3108*8c35d5eeSXin Li This is preferable because it does not cons. 3109*8c35d5eeSXin Li </p> 3110*8c35d5eeSXin Li <p> 3111*8c35d5eeSXin Li You should use <code>ZEROP</code>, 3112*8c35d5eeSXin Li <code>PLUSP</code>, or <code>MINUSP</code>, 3113*8c35d5eeSXin Li instead of comparing a value to <code>0</code> or <code>0.0</code>. 3114*8c35d5eeSXin Li </p> 3115*8c35d5eeSXin Li <p> 3116*8c35d5eeSXin Li You must not use exact comparison on floating point numbers, 3117*8c35d5eeSXin Li since the vague nature of floating point arithmetic 3118*8c35d5eeSXin Li can produce little "errors" in numeric value. 3119*8c35d5eeSXin Li You should compare absolute values to a threshhold. 3120*8c35d5eeSXin Li </p> 3121*8c35d5eeSXin Li <p> 3122*8c35d5eeSXin Li You must use <code>=</code> to compare numbers, 3123*8c35d5eeSXin Li unless you really mean for <code>0</code>, 3124*8c35d5eeSXin Li <code>0.0</code> and <code>-0.0</code> to compare unequal, 3125*8c35d5eeSXin Li in which case you should use <code>EQL</code>. 3126*8c35d5eeSXin Li Then again, you must not usually use exact comparison 3127*8c35d5eeSXin Li on floating point numbers. 3128*8c35d5eeSXin Li </p> 3129*8c35d5eeSXin Li <p> 3130*8c35d5eeSXin Li Monetary amounts should be using decimal (rational) numbers 3131*8c35d5eeSXin Li to avoid the complexities and rounding errors 3132*8c35d5eeSXin Li of floating-point arithmetic. 3133*8c35d5eeSXin Li Libraries such as 3134*8c35d5eeSXin Li <a href="http://wukix.com/lisp-decimals">wu-decimal</a> 3135*8c35d5eeSXin Li may help you; 3136*8c35d5eeSXin Li once again, if this library is not satisfactory, see above about 3137*8c35d5eeSXin Li <a href="#Using_Libraries">Using Libraries</a> and 3138*8c35d5eeSXin Li <a href="#Open-Sourcing_Code">Open-Sourcing Code</a>. 3139*8c35d5eeSXin Li </p> 3140*8c35d5eeSXin Li 3141*8c35d5eeSXin Li </BODY> 3142*8c35d5eeSXin Li </STYLEPOINT> 3143*8c35d5eeSXin Li <STYLEPOINT title="Iteration"> 3144*8c35d5eeSXin Li <SUMMARY> 3145*8c35d5eeSXin Li Use the appropriate form for iteration. 3146*8c35d5eeSXin Li </SUMMARY> 3147*8c35d5eeSXin Li <BODY> 3148*8c35d5eeSXin Li <p> 3149*8c35d5eeSXin Li You should use simpler forms such as 3150*8c35d5eeSXin Li <code>DOLIST</code> or <code>DOTIMES</code> 3151*8c35d5eeSXin Li instead of <code>LOOP</code> 3152*8c35d5eeSXin Li in simple cases when you're not going to use any 3153*8c35d5eeSXin Li of the <code>LOOP</code> facilities such as 3154*8c35d5eeSXin Li bindings, collection or block return. 3155*8c35d5eeSXin Li </p> 3156*8c35d5eeSXin Li <p> 3157*8c35d5eeSXin Li Use the <code>WITH</code> clause of <code>LOOP</code> 3158*8c35d5eeSXin Li when it will avoid a level of nesting with <code>LET</code>. 3159*8c35d5eeSXin Li You may use <code>LET</code> if it makes it clearer 3160*8c35d5eeSXin Li to return one of bound variables after the <code>LOOP</code>, 3161*8c35d5eeSXin Li rather than use a clumsy <code>FINALLY (RETURN ...)</code> form. 3162*8c35d5eeSXin Li </p> 3163*8c35d5eeSXin Li <p> 3164*8c35d5eeSXin Li In the body of a <code>DOTIMES</code>, 3165*8c35d5eeSXin Li do not set the iteration variable. 3166*8c35d5eeSXin Li (CCL will issue a compiler warning if you do.) 3167*8c35d5eeSXin Li </p> 3168*8c35d5eeSXin Li <p> 3169*8c35d5eeSXin Li Most systems use unadorned symbols in the current package 3170*8c35d5eeSXin Li as <code>LOOP</code> keywords. 3171*8c35d5eeSXin Li Other systems use actual <code>:keywords</code> 3172*8c35d5eeSXin Li from the <code>KEYWORD</code> package 3173*8c35d5eeSXin Li as <code>LOOP</code> keywords. 3174*8c35d5eeSXin Li You must be consistent with the convention used in your system. 3175*8c35d5eeSXin Li </p> 3176*8c35d5eeSXin Li </BODY> 3177*8c35d5eeSXin Li </STYLEPOINT> 3178*8c35d5eeSXin Li <STYLEPOINT title="I/O"> 3179*8c35d5eeSXin Li <SUMMARY> 3180*8c35d5eeSXin Li Use the appropriate I/O functions. 3181*8c35d5eeSXin Li </SUMMARY> 3182*8c35d5eeSXin Li <BODY> 3183*8c35d5eeSXin Li <p> 3184*8c35d5eeSXin Li When writing a server, 3185*8c35d5eeSXin Li code must not send output to the standard streams such as 3186*8c35d5eeSXin Li <code>*STANDARD-OUTPUT*</code> or <code>*ERROR-OUTPUT*</code>. 3187*8c35d5eeSXin Li Instead, code must use the proper logging framework 3188*8c35d5eeSXin Li to output messages for debugging. 3189*8c35d5eeSXin Li We are running as a server, so there is no console! 3190*8c35d5eeSXin Li </p> 3191*8c35d5eeSXin Li <p> 3192*8c35d5eeSXin Li Code must not use <code>PRINT-OBJECT</code> 3193*8c35d5eeSXin Li to communicate with a user — 3194*8c35d5eeSXin Li <code>PRINT-OBJECT</code> is for debugging purposes only. 3195*8c35d5eeSXin Li Modifying any <code>PRINT-OBJECT</code> method 3196*8c35d5eeSXin Li must not break any public interfaces. 3197*8c35d5eeSXin Li </p> 3198*8c35d5eeSXin Li <p> 3199*8c35d5eeSXin Li You should not use a sequence of <code>WRITE-XXX</code> 3200*8c35d5eeSXin Li where a single <code>FORMAT</code> string could be used. 3201*8c35d5eeSXin Li Using format allows you 3202*8c35d5eeSXin Li to parameterize the format control string in the future 3203*8c35d5eeSXin Li if the need arises. 3204*8c35d5eeSXin Li </p> 3205*8c35d5eeSXin Li <p> 3206*8c35d5eeSXin Li You should use <code>WRITE-CHAR</code> to emit a character 3207*8c35d5eeSXin Li rather than <code>WRITE-STRING</code> 3208*8c35d5eeSXin Li to emit a single-character string. 3209*8c35d5eeSXin Li </p> 3210*8c35d5eeSXin Li <p> 3211*8c35d5eeSXin Li You should not use <code>(format nil "~A" value)</code>; 3212*8c35d5eeSXin Li you should use <code>PRINC-TO-STRING</code> instead. 3213*8c35d5eeSXin Li </p> 3214*8c35d5eeSXin Li <p> 3215*8c35d5eeSXin Li You should use <code>~<Newline></code> 3216*8c35d5eeSXin Li or <code>~@<Newline></code> in format strings 3217*8c35d5eeSXin Li to keep them from wrapping in 100-column editor windows, 3218*8c35d5eeSXin Li or to indent sections or clauses to make them more readable. 3219*8c35d5eeSXin Li </p> 3220*8c35d5eeSXin Li <p> 3221*8c35d5eeSXin Li You should not use <code>STRING-UPCASE</code> 3222*8c35d5eeSXin Li or <code>STRING-DOWNCASE</code> 3223*8c35d5eeSXin Li on format control parameters; 3224*8c35d5eeSXin Li instead, it should use <code>"~:@(~A~)"</code> or <code>"~(~A~)"</code>. 3225*8c35d5eeSXin Li </p> 3226*8c35d5eeSXin Li <p> 3227*8c35d5eeSXin Li Be careful when using the <code>FORMAT</code> conditional directive. 3228*8c35d5eeSXin Li The parameters are easy to forget. 3229*8c35d5eeSXin Li </p> 3230*8c35d5eeSXin Li <dl> 3231*8c35d5eeSXin Li <dt>No parameters, e.g. <code>"~[Siamese~;Manx~;Persian~] Cat"</code></dt> 3232*8c35d5eeSXin Li <dd> 3233*8c35d5eeSXin Li Take one format argument, which should be an integer. 3234*8c35d5eeSXin Li Use it to choose a clause. Clause numbers are zero-based. 3235*8c35d5eeSXin Li If the number is out of range, just print nothing. 3236*8c35d5eeSXin Li You can provide a default value 3237*8c35d5eeSXin Li by putting a <code>":"</code> in front of the last <code>";"</code>. 3238*8c35d5eeSXin Li E.g. in <code>"~[Siamese~;Manx~;Persian~:;Alley~] Cat"</code>, 3239*8c35d5eeSXin Li an out-of-range arg prints <code>"Alley"</code>. 3240*8c35d5eeSXin Li </dd> 3241*8c35d5eeSXin Li <dt><code>:</code> parameter, e.g. <code>"~:[Siamese~;Manx~]"</code></dt> 3242*8c35d5eeSXin Li <dd> 3243*8c35d5eeSXin Li Take one format argument. If it's <code>NIL</code>, 3244*8c35d5eeSXin Li use the first clause, otherwise use the second clause. 3245*8c35d5eeSXin Li </dd> 3246*8c35d5eeSXin Li <dt><code>@</code> parameter, e.g. <code>"~@[Siamese ~a~]"</code></dt> 3247*8c35d5eeSXin Li <dd> 3248*8c35d5eeSXin Li If the next format argument is true, 3249*8c35d5eeSXin Li use the choice, but do NOT take the argument. 3250*8c35d5eeSXin Li If it's false, take one format argument and print nothing. 3251*8c35d5eeSXin Li (Normally the clause uses the format argument.) 3252*8c35d5eeSXin Li </dd> 3253*8c35d5eeSXin Li <dt><code>#</code> parameter, e.g. <code>"~#[ none~; ~s~; ~s and ~s~]"</code></dt> 3254*8c35d5eeSXin Li <dd> 3255*8c35d5eeSXin Li Use the number of arguments to format 3256*8c35d5eeSXin Li as the number to choose a clause. 3257*8c35d5eeSXin Li The same as no parameters in all other ways. 3258*8c35d5eeSXin Li Here's the full hairy example: 3259*8c35d5eeSXin Li <code>"Items:~#[ none~; ~S~; ~S and ~S~:;~@{~#[~; and~] ~S~^ ,~}~]."</code> 3260*8c35d5eeSXin Li </dd> 3261*8c35d5eeSXin Li </dl> 3262*8c35d5eeSXin Li </BODY> 3263*8c35d5eeSXin Li </STYLEPOINT> 3264*8c35d5eeSXin Li</CATEGORY> 3265*8c35d5eeSXin Li 3266*8c35d5eeSXin Li<CATEGORY title="Optimization"> 3267*8c35d5eeSXin Li <STYLEPOINT title="Avoid Allocation"> 3268*8c35d5eeSXin Li <SUMMARY> 3269*8c35d5eeSXin Li You should avoid unnecessary allocation of memory. 3270*8c35d5eeSXin Li </SUMMARY> 3271*8c35d5eeSXin Li <BODY> 3272*8c35d5eeSXin Li <p> 3273*8c35d5eeSXin Li In a language with automatic storage management (such as Lisp or Java), 3274*8c35d5eeSXin Li the colloquial phrase "memory leak" refers to situation 3275*8c35d5eeSXin Li where storage that is not actually needed 3276*8c35d5eeSXin Li nevertheless does not get deallocated, 3277*8c35d5eeSXin Li because it is still reachable. 3278*8c35d5eeSXin Li </p> 3279*8c35d5eeSXin Li <p> 3280*8c35d5eeSXin Li You should be careful that when you create objects, 3281*8c35d5eeSXin Li you don't leave them reachable after they are no longer needed! 3282*8c35d5eeSXin Li </p> 3283*8c35d5eeSXin Li <p> 3284*8c35d5eeSXin Li Here's a particular trap-for-the-unwary in Common Lisp. 3285*8c35d5eeSXin Li If you make an array with a fill pointer, and put objects in it, 3286*8c35d5eeSXin Li and then set the fill pointer back to zero, 3287*8c35d5eeSXin Li those objects are still reachable as far as Lisp goes 3288*8c35d5eeSXin Li (the Common Lisp spec says that it's still OK 3289*8c35d5eeSXin Li to refer to the array entries past the end of the fill pointer). 3290*8c35d5eeSXin Li </p> 3291*8c35d5eeSXin Li <p> 3292*8c35d5eeSXin Li Don't cons (i.e., allocate) unnecessarily. 3293*8c35d5eeSXin Li Garbage collection is not magic. 3294*8c35d5eeSXin Li Excessive allocation is usually a performance problem. 3295*8c35d5eeSXin Li </p> 3296*8c35d5eeSXin Li </BODY> 3297*8c35d5eeSXin Li </STYLEPOINT> 3298*8c35d5eeSXin Li <STYLEPOINT title="Unsafe Operations"> 3299*8c35d5eeSXin Li <SUMMARY> 3300*8c35d5eeSXin Li You must only use faster unsafe operations 3301*8c35d5eeSXin Li when there is a clear performance need 3302*8c35d5eeSXin Li and you can document why it's correct. 3303*8c35d5eeSXin Li </SUMMARY> 3304*8c35d5eeSXin Li <BODY> 3305*8c35d5eeSXin Li <p> 3306*8c35d5eeSXin Li Common Lisp implementations often provide backdoors 3307*8c35d5eeSXin Li to compute some operations faster in an unsafe way. 3308*8c35d5eeSXin Li For instance, some libraries provide arithmetic operations 3309*8c35d5eeSXin Li that are designed to be used with fixnums only, 3310*8c35d5eeSXin Li and yield the correct result faster if provided proper arguments. 3311*8c35d5eeSXin Li The downside is that the result of such operations 3312*8c35d5eeSXin Li is incorrect in case of overflow, and can 3313*8c35d5eeSXin Li have undefined behavior when called with anything but fixnums. 3314*8c35d5eeSXin Li </p> 3315*8c35d5eeSXin Li 3316*8c35d5eeSXin Li <p> 3317*8c35d5eeSXin Li More generally, unsafe operations 3318*8c35d5eeSXin Li will yield the correct result faster 3319*8c35d5eeSXin Li than would the equivalent safe operation 3320*8c35d5eeSXin Li if the arguments satisfy some invariant such as 3321*8c35d5eeSXin Li being of the correct type and small enough; 3322*8c35d5eeSXin Li however if the arguments fail to satisfy the required invariants, 3323*8c35d5eeSXin Li then the operation may have undefined behavior, 3324*8c35d5eeSXin Li such as crashing the software, or, 3325*8c35d5eeSXin Li which is sometimes worse, silently giving wrong answers. 3326*8c35d5eeSXin Li Depending on whether the software is piloting an aircraft 3327*8c35d5eeSXin Li or other life-critical device, 3328*8c35d5eeSXin Li or whether it is accounting for large amounts money, 3329*8c35d5eeSXin Li such undefined behavior can kill or bankrupt people. 3330*8c35d5eeSXin Li Yet proper speed can sometimes make the difference between 3331*8c35d5eeSXin Li software that's unusably slow and software that does its job, 3332*8c35d5eeSXin Li or between software that is a net loss 3333*8c35d5eeSXin Li and software that can yield a profit. 3334*8c35d5eeSXin Li </p> 3335*8c35d5eeSXin Li <p> 3336*8c35d5eeSXin Li You must not define or use unsafe operations without both 3337*8c35d5eeSXin Li profiling results indicating the need for this optimization, 3338*8c35d5eeSXin Li and careful documentation explaining why it is safe to use them. 3339*8c35d5eeSXin Li Unsafe operations should be restricted to internal functions; 3340*8c35d5eeSXin Li you should carefully documented how unsafe it is 3341*8c35d5eeSXin Li to use these functions with the wrong arguments. 3342*8c35d5eeSXin Li You should only use unsafe operations 3343*8c35d5eeSXin Li inside functions internal to a package and 3344*8c35d5eeSXin Li you should document the use of the declarations, 3345*8c35d5eeSXin Li since calling the functions with arguments of the wrong type 3346*8c35d5eeSXin Li can lead to undefined behavior. 3347*8c35d5eeSXin Li Use <code>check-type</code> in functions exported from a package 3348*8c35d5eeSXin Li to sanitize input arguments, 3349*8c35d5eeSXin Li so that internal functions are never passed illegal values. 3350*8c35d5eeSXin Li </p> 3351*8c35d5eeSXin Li <p> 3352*8c35d5eeSXin Li On some compilers, 3353*8c35d5eeSXin Li new unsafe operations 3354*8c35d5eeSXin Li can usually be defined by combining 3355*8c35d5eeSXin Li type declarations with an <code>OPTIMIZE</code> declaration 3356*8c35d5eeSXin Li that has sufficiently high <code>SPEED</code> and low <code>SAFETY</code>. 3357*8c35d5eeSXin Li In addition to providing more speed for production code, 3358*8c35d5eeSXin Li such declarations may more helpful 3359*8c35d5eeSXin Li than <code>check-type</code> assertions 3360*8c35d5eeSXin Li for finding bugs at compile-time, 3361*8c35d5eeSXin Li on compilers that have type inference. 3362*8c35d5eeSXin Li These compilers may interpret those declarations as assertions 3363*8c35d5eeSXin Li if you switch to safer and slower optimize settings; 3364*8c35d5eeSXin Li this is good to locate a dynamic error in your code during development, 3365*8c35d5eeSXin Li but is not to be used for production code since 3366*8c35d5eeSXin Li it defeats the purpose of declarations as a performance trick. 3367*8c35d5eeSXin Li </p> 3368*8c35d5eeSXin Li 3369*8c35d5eeSXin Li </BODY> 3370*8c35d5eeSXin Li </STYLEPOINT> 3371*8c35d5eeSXin Li <STYLEPOINT title="DYNAMIC-EXTENT"> 3372*8c35d5eeSXin Li <SUMMARY> 3373*8c35d5eeSXin Li You should only use <code>DYNAMIC-EXTENT</code> 3374*8c35d5eeSXin Li where it matters for performance, 3375*8c35d5eeSXin Li and you can document why it is correct. 3376*8c35d5eeSXin Li </SUMMARY> 3377*8c35d5eeSXin Li <BODY> 3378*8c35d5eeSXin Li <p> 3379*8c35d5eeSXin Li <code>DYNAMIC-EXTENT</code> declarations are 3380*8c35d5eeSXin Li a particular case of 3381*8c35d5eeSXin Li <a href="#Unsafe_Operations">unsafe operations</a>. 3382*8c35d5eeSXin Li </p> 3383*8c35d5eeSXin Li <p> 3384*8c35d5eeSXin Li The purpose of a <code>DYNAMIC-EXTENT</code> declaration 3385*8c35d5eeSXin Li is to improve performance by reducing garbage collection 3386*8c35d5eeSXin Li in cases where it appears to be obvious that an object's lifetime 3387*8c35d5eeSXin Li is within the "dynamic extent" of a function. 3388*8c35d5eeSXin Li That means the object is created at some point 3389*8c35d5eeSXin Li after the function is called, and 3390*8c35d5eeSXin Li the object is always inaccessible after the function exits by any means. 3391*8c35d5eeSXin Li </p> 3392*8c35d5eeSXin Li <p> 3393*8c35d5eeSXin Li By declaring a variable or a local function <code>DYNAMIC-EXTENT</code>, 3394*8c35d5eeSXin Li the programmer <em>asserts</em> to Lisp 3395*8c35d5eeSXin Li that any object that is ever a value of that variable 3396*8c35d5eeSXin Li or the closure that is the definition of the function 3397*8c35d5eeSXin Li has a lifetime within the dynamic extent of the (innermost) function 3398*8c35d5eeSXin Li that declares the variable. 3399*8c35d5eeSXin Li </p> 3400*8c35d5eeSXin Li <p> 3401*8c35d5eeSXin Li The Lisp implementation is then free to use that information 3402*8c35d5eeSXin Li to make the program faster. 3403*8c35d5eeSXin Li Typically, Lisp implementations can take advantage of this knowledge 3404*8c35d5eeSXin Li to stack-allocate: 3405*8c35d5eeSXin Li </p> 3406*8c35d5eeSXin Li <ul> 3407*8c35d5eeSXin Li <li> 3408*8c35d5eeSXin Li The lists created to store <code>&REST</code> parameters. 3409*8c35d5eeSXin Li </li> 3410*8c35d5eeSXin Li <li> 3411*8c35d5eeSXin Li Lists, vectors and structures allocated within a function. 3412*8c35d5eeSXin Li </li> 3413*8c35d5eeSXin Li <li> 3414*8c35d5eeSXin Li Closures. 3415*8c35d5eeSXin Li </li> 3416*8c35d5eeSXin Li </ul> 3417*8c35d5eeSXin Li <p> 3418*8c35d5eeSXin Li If the assertion is wrong, i.e. if the programmer's claim is not true, 3419*8c35d5eeSXin Li the results can be <em>catastrophic</em>: 3420*8c35d5eeSXin Li Lisp can terminate any time after the function returns, 3421*8c35d5eeSXin Li or it can hang forever, or — worst of all — 3422*8c35d5eeSXin Li it can produce incorrect results without any runtime error! 3423*8c35d5eeSXin Li </p> 3424*8c35d5eeSXin Li <p> 3425*8c35d5eeSXin Li Even if the assertion is correct, 3426*8c35d5eeSXin Li future changes to the function might introduce 3427*8c35d5eeSXin Li a violation of the assertion. 3428*8c35d5eeSXin Li This increases the danger. 3429*8c35d5eeSXin Li </p> 3430*8c35d5eeSXin Li <p> 3431*8c35d5eeSXin Li In most cases, such objects are ephemeral. 3432*8c35d5eeSXin Li Modern Lisp implementations use generational garbage collectors, 3433*8c35d5eeSXin Li which are quite efficient under these circumstances. 3434*8c35d5eeSXin Li </p> 3435*8c35d5eeSXin Li <p> 3436*8c35d5eeSXin Li Therefore, <code>DYNAMIC-EXTENT</code> declarations 3437*8c35d5eeSXin Li should be used sparingly. You must only use them if: 3438*8c35d5eeSXin Li </p> 3439*8c35d5eeSXin Li <ol> 3440*8c35d5eeSXin Li <li> 3441*8c35d5eeSXin Li There is some good reason to think that the overall effect 3442*8c35d5eeSXin Li on performance is noticeable, and 3443*8c35d5eeSXin Li </li> 3444*8c35d5eeSXin Li <li> 3445*8c35d5eeSXin Li It is absolutely clear that the assertion is true. 3446*8c35d5eeSXin Li </li> 3447*8c35d5eeSXin Li <li> 3448*8c35d5eeSXin Li It is quite unlikely that the code will be changed 3449*8c35d5eeSXin Li in ways that cause the declaration to become false. 3450*8c35d5eeSXin Li </li> 3451*8c35d5eeSXin Li </ol> 3452*8c35d5eeSXin Li <p> 3453*8c35d5eeSXin Li Point (1) is a special case of 3454*8c35d5eeSXin Li the principle of avoiding premature optimization. 3455*8c35d5eeSXin Li An optimization like this only matters if such objects 3456*8c35d5eeSXin Li are allocated at a very high rate, e.g. "inside an inner loop". 3457*8c35d5eeSXin Li </p> 3458*8c35d5eeSXin Li <p> 3459*8c35d5eeSXin Li Note that is relatively easy to ascertain that 3460*8c35d5eeSXin Li a function will not escape the dynamic extent of the current call frame 3461*8c35d5eeSXin Li by analyzing where the function is called and 3462*8c35d5eeSXin Li what other functions it is passed to; 3463*8c35d5eeSXin Li therefore, you should somewhat wary of declaring a function 3464*8c35d5eeSXin Li <code>DYNAMIC-EXTENT</code>, but this is not a high-stress declaration. 3465*8c35d5eeSXin Li On the other hand, it is much harder to ascertain that 3466*8c35d5eeSXin Li none of the objects ever bound or assigned to that variable 3467*8c35d5eeSXin Li and none of their sub-objects 3468*8c35d5eeSXin Li will escape the dynamic extent of the current call frame, 3469*8c35d5eeSXin Li and that they still won't in any future modification of a function. 3470*8c35d5eeSXin Li Therefore, you should be extremely wary 3471*8c35d5eeSXin Li of declaring a variable <code>DYNAMIC-EXTENT</code>. 3472*8c35d5eeSXin Li </p> 3473*8c35d5eeSXin Li <p> 3474*8c35d5eeSXin Li It's usually hard to predict the effect of such optimization on performance. 3475*8c35d5eeSXin Li When writing a function or macro 3476*8c35d5eeSXin Li that is part of a library of reusable code, 3477*8c35d5eeSXin Li there's no a priori way to know how often the code will run. 3478*8c35d5eeSXin Li Ideally, tools would be available to discover 3479*8c35d5eeSXin Li the availability and suitability of using such an optimization 3480*8c35d5eeSXin Li based on running simulations and test cases, but 3481*8c35d5eeSXin Li in practice this isn't as easy as it ought to be. 3482*8c35d5eeSXin Li It's a tradeoff. 3483*8c35d5eeSXin Li If you're very, very sure that the assertion is true 3484*8c35d5eeSXin Li (that any object bound to the variable and any of its sub-objects 3485*8c35d5eeSXin Li are only used within the dynamic extent of the specified scope), 3486*8c35d5eeSXin Li and it's not obvious how much time will be saved 3487*8c35d5eeSXin Li and it's not easy to measure, 3488*8c35d5eeSXin Li then it may be better to put in the declaration than to leave it out. 3489*8c35d5eeSXin Li (Ideally it would be easier to make such measurements 3490*8c35d5eeSXin Li than it actually is.) 3491*8c35d5eeSXin Li </p> 3492*8c35d5eeSXin Li </BODY> 3493*8c35d5eeSXin Li </STYLEPOINT> 3494*8c35d5eeSXin Li <STYLEPOINT title="REDUCE vs APPLY"> 3495*8c35d5eeSXin Li <SUMMARY> 3496*8c35d5eeSXin Li You should use <code>REDUCE</code> 3497*8c35d5eeSXin Li instead of <code>APPLY</code> where appropriate. 3498*8c35d5eeSXin Li </SUMMARY> 3499*8c35d5eeSXin Li <BODY> 3500*8c35d5eeSXin Li <p> 3501*8c35d5eeSXin Li You should use <code>REDUCE</code> 3502*8c35d5eeSXin Li instead of <code>APPLY</code> and a consed-up list, 3503*8c35d5eeSXin Li where the semantics of the first operator argument 3504*8c35d5eeSXin Li otherwise guarantees the same semantics. 3505*8c35d5eeSXin Li Of course, you must use <code>APPLY</code> 3506*8c35d5eeSXin Li if it does what you want and <code>REDUCE</code> doesn't. 3507*8c35d5eeSXin Li For instance: 3508*8c35d5eeSXin Li </p> 3509*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 3510*8c35d5eeSXin Li ;; Bad 3511*8c35d5eeSXin Li (apply #'+ (mapcar #'acc frobs)) 3512*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 3513*8c35d5eeSXin Li <CODE_SNIPPET> 3514*8c35d5eeSXin Li ;; Better 3515*8c35d5eeSXin Li (reduce #'+ frobs :key #'acc :initial-value 0) 3516*8c35d5eeSXin Li </CODE_SNIPPET> 3517*8c35d5eeSXin Li <p> 3518*8c35d5eeSXin Li This is preferable because it does not do extra consing, 3519*8c35d5eeSXin Li and does not risk going beyond <code>CALL-ARGUMENTS-LIMIT</code> 3520*8c35d5eeSXin Li on implementations where that limit is small, 3521*8c35d5eeSXin Li which could blow away the stack on long lists 3522*8c35d5eeSXin Li (we want to avoid gratuitous non-portability in our code). 3523*8c35d5eeSXin Li </p> 3524*8c35d5eeSXin Li <p> 3525*8c35d5eeSXin Li However, you must be careful not to use <code>REDUCE</code> 3526*8c35d5eeSXin Li in ways that needlessly increase 3527*8c35d5eeSXin Li the complexity class of the computation. 3528*8c35d5eeSXin Li For instance, <code>(REDUCE 'STRCAT ...)</code> is <i>O(n^2)</i> 3529*8c35d5eeSXin Li when an appropriate implementation is only <i>O(n)</i>. 3530*8c35d5eeSXin Li Moreover, <code>(REDUCE 'APPEND ...)</code> 3531*8c35d5eeSXin Li is also <i>O(n^2)</i> unless you specify <code>:FROM-END T</code>. 3532*8c35d5eeSXin Li In such cases, you MUST NOT use <code>REDUCE</code>, 3533*8c35d5eeSXin Li and you MUST NOT use <code>(APPLY 'STRCAT ...)</code> 3534*8c35d5eeSXin Li or <code>(APPLY 'APPEND ...)</code> either. 3535*8c35d5eeSXin Li Instead you MUST use proper abstractions 3536*8c35d5eeSXin Li from a suitable library (that you may have to contribute to) 3537*8c35d5eeSXin Li that properly handles those cases 3538*8c35d5eeSXin Li without burdening users with implementation details. 3539*8c35d5eeSXin Li See for instance <code>UIOP:REDUCE/STRCAT</code>. 3540*8c35d5eeSXin Li </p> 3541*8c35d5eeSXin Li 3542*8c35d5eeSXin Li </BODY> 3543*8c35d5eeSXin Li </STYLEPOINT> 3544*8c35d5eeSXin Li <STYLEPOINT title="Avoid NCONC"> 3545*8c35d5eeSXin Li <SUMMARY> 3546*8c35d5eeSXin Li You should not use <code>NCONC</code>; 3547*8c35d5eeSXin Li you should use <code>APPEND</code> instead, 3548*8c35d5eeSXin Li or better, better data structures. 3549*8c35d5eeSXin Li </SUMMARY> 3550*8c35d5eeSXin Li <BODY> 3551*8c35d5eeSXin Li <p> 3552*8c35d5eeSXin Li You should almost never use <code>NCONC</code>. 3553*8c35d5eeSXin Li You should use <code>APPEND</code> 3554*8c35d5eeSXin Li when you don't depend on any side-effect. 3555*8c35d5eeSXin Li You should use <code>ALEXANDRIA:APPENDF</code> 3556*8c35d5eeSXin Li when you need to update a variable. 3557*8c35d5eeSXin Li You should probably not depend on games 3558*8c35d5eeSXin Li being played with the <code>CDR</code> 3559*8c35d5eeSXin Li of the current CONS cell 3560*8c35d5eeSXin Li (which some might argue is suggested but not guaranteed by the specification); 3561*8c35d5eeSXin Li if you do, you must include a prominent 3562*8c35d5eeSXin Li comment explaining the use of <code>NCONC</code>; 3563*8c35d5eeSXin Li and you should probably reconsider your data representation strategy. 3564*8c35d5eeSXin Li </p> 3565*8c35d5eeSXin Li <p> 3566*8c35d5eeSXin Li By extension, you should avoid <code>MAPCAN</code> 3567*8c35d5eeSXin Li or the <code>NCONC</code> feature of <code>LOOP</code>. 3568*8c35d5eeSXin Li You should instead respectively use 3569*8c35d5eeSXin Li <code>ALEXANDRIA:MAPPEND</code> 3570*8c35d5eeSXin Li and the <code>APPEND</code> feature of <code>LOOP</code>. 3571*8c35d5eeSXin Li </p> 3572*8c35d5eeSXin Li <p> 3573*8c35d5eeSXin Li <code>NCONC</code> is very seldom a good idea, 3574*8c35d5eeSXin Li since its time complexity class is no better than <code>APPEND</code>, 3575*8c35d5eeSXin Li its space complexity class also is no better than <code>APPEND</code> 3576*8c35d5eeSXin Li in the common case where no one else is sharing the side-effected list, 3577*8c35d5eeSXin Li and its bug complexity class is way higher than <code>APPEND</code>. 3578*8c35d5eeSXin Li </p> 3579*8c35d5eeSXin Li <p> 3580*8c35d5eeSXin Li If the small performance hit due 3581*8c35d5eeSXin Li to <code>APPEND</code> vs. <code>NCONC</code> 3582*8c35d5eeSXin Li is a limiting factor in your program, 3583*8c35d5eeSXin Li you have a big problem and are probably using the wrong data structure: 3584*8c35d5eeSXin Li you should be using sequences with constant-time append 3585*8c35d5eeSXin Li (see Okasaki's book, and add them to lisp-interface-library), 3586*8c35d5eeSXin Li or more simply you should be accumulating data in a tree 3587*8c35d5eeSXin Li that will get flattened once in linear time 3588*8c35d5eeSXin Li after the accumulation phase is complete. 3589*8c35d5eeSXin Li </p> 3590*8c35d5eeSXin Li <p> 3591*8c35d5eeSXin Li You may only use <code>NCONC</code>, <code>MAPCAN</code> 3592*8c35d5eeSXin Li or the <code>NCONC</code> feature of <code>LOOP</code> 3593*8c35d5eeSXin Li in low-level functions where performance matters, 3594*8c35d5eeSXin Li where the use of lists as a data structure has been vetted 3595*8c35d5eeSXin Li because these lists are known to be short, 3596*8c35d5eeSXin Li and when the function or expression the result of which are accumulated 3597*8c35d5eeSXin Li explicitly promises in its contract that it only returns fresh lists 3598*8c35d5eeSXin Li (in particular, it can't be a constant quote or backquote expression). 3599*8c35d5eeSXin Li Even then, the use of such primitives must be rare, 3600*8c35d5eeSXin Li and accompanied by justifying documentation. 3601*8c35d5eeSXin Li </p> 3602*8c35d5eeSXin Li </BODY> 3603*8c35d5eeSXin Li </STYLEPOINT> 3604*8c35d5eeSXin Li</CATEGORY> 3605*8c35d5eeSXin Li 3606*8c35d5eeSXin Li<CATEGORY title="Pitfalls"> 3607*8c35d5eeSXin Li <STYLEPOINT title="#'FUN vs. 'FUN"> 3608*8c35d5eeSXin Li <SUMMARY> 3609*8c35d5eeSXin Li You should usually refer to a function as <code>#'FUN</code> rather than <code>'FUN</code>. 3610*8c35d5eeSXin Li </SUMMARY> 3611*8c35d5eeSXin Li <BODY> 3612*8c35d5eeSXin Li <p> 3613*8c35d5eeSXin Li The former, which reads as <code>(FUNCTION FUN)</code>, 3614*8c35d5eeSXin Li refers to the function object, and is lexically scoped. 3615*8c35d5eeSXin Li The latter, which reads as <code>(QUOTE FUN)</code>, 3616*8c35d5eeSXin Li refers to the symbol, which when called 3617*8c35d5eeSXin Li uses the global <code>FDEFINITION</code> of the symbol. 3618*8c35d5eeSXin Li </p> 3619*8c35d5eeSXin Li <p> 3620*8c35d5eeSXin Li When using functions that take a functional argument 3621*8c35d5eeSXin Li (e.g., <code>MAPCAR</code>, <code>APPLY</code>, 3622*8c35d5eeSXin Li <code>:TEST</code> and <code>:KEY</code> arguments), 3623*8c35d5eeSXin Li you should use the <code>#'</code> to refer to the function, 3624*8c35d5eeSXin Li not just single quote. 3625*8c35d5eeSXin Li </p> 3626*8c35d5eeSXin Li <p> 3627*8c35d5eeSXin Li An exception is when you explicitly want dynamic linking, 3628*8c35d5eeSXin Li because you anticipate that 3629*8c35d5eeSXin Li the global function binding will be updated. 3630*8c35d5eeSXin Li </p> 3631*8c35d5eeSXin Li <p> 3632*8c35d5eeSXin Li Another exception is when you explicitly want to access 3633*8c35d5eeSXin Li a global function binding, 3634*8c35d5eeSXin Li and avoid a possible shadowing lexical binding. 3635*8c35d5eeSXin Li This shouldn't happen often, as it is usually a bad idea 3636*8c35d5eeSXin Li to shadow a function when you will want to use the shadowed function; 3637*8c35d5eeSXin Li just use a different name for the lexical function. 3638*8c35d5eeSXin Li </p> 3639*8c35d5eeSXin Li <p> 3640*8c35d5eeSXin Li You must consistently use either <code>#'(lambda ...)</code> 3641*8c35d5eeSXin Li or <code>(lambda ...)</code> without <code>#'</code> everywhere. 3642*8c35d5eeSXin Li Unlike the case of <code>#'symbol</code> vs <code>'symbol</code>, 3643*8c35d5eeSXin Li it is only a syntactic difference with no semantic impact, 3644*8c35d5eeSXin Li except that the former works on Genera and the latter doesn't. 3645*8c35d5eeSXin Li 3646*8c35d5eeSXin Li You must use the former style if your code is intended as a library 3647*8c35d5eeSXin Li with maximal compatibility to all Common Lisp implementations; 3648*8c35d5eeSXin Li otherwise, it is optional which style you use. 3649*8c35d5eeSXin Li <code>#'</code> may be seen as a hint 3650*8c35d5eeSXin Li that you're introducing a function in expression context; 3651*8c35d5eeSXin Li but the <code>lambda</code> itself is usually sufficient hint, 3652*8c35d5eeSXin Li and concision is good. 3653*8c35d5eeSXin Li Choose wisely, but above all, 3654*8c35d5eeSXin Li consistently with yourself and other developers, 3655*8c35d5eeSXin Li within a same file, package, system, project, etc. 3656*8c35d5eeSXin Li </p> 3657*8c35d5eeSXin Li <p> 3658*8c35d5eeSXin Li Note that if you start writing a new system 3659*8c35d5eeSXin Li in a heavily functional style, 3660*8c35d5eeSXin Li you may consider using 3661*8c35d5eeSXin Li <a href="http://cliki.net/lambda-reader">lambda-reader</a>, 3662*8c35d5eeSXin Li a system that lets you use the unicode character <code>λ</code> 3663*8c35d5eeSXin Li instead of <code>LAMBDA</code>. 3664*8c35d5eeSXin Li But you must not start using such a syntactic extension 3665*8c35d5eeSXin Li in an existing system without getting permission from other developers. 3666*8c35d5eeSXin Li </p> 3667*8c35d5eeSXin Li </BODY> 3668*8c35d5eeSXin Li </STYLEPOINT> 3669*8c35d5eeSXin Li <STYLEPOINT title="Pathnames"> 3670*8c35d5eeSXin Li <SUMMARY> 3671*8c35d5eeSXin Li Common Lisp pathnames are tricky. Be aware of pitfalls. Use <code>UIOP</code>. 3672*8c35d5eeSXin Li </SUMMARY> 3673*8c35d5eeSXin Li <BODY> 3674*8c35d5eeSXin Li <p> 3675*8c35d5eeSXin Li It is surprisingly hard to properly deal with pathnames in Common Lisp. 3676*8c35d5eeSXin Li </p> 3677*8c35d5eeSXin Li <p> 3678*8c35d5eeSXin Li <code>ASDF 3</code> comes with a portability library <code>UIOP</code> 3679*8c35d5eeSXin Li that makes it <em>much</em> easier to deal with pathnames 3680*8c35d5eeSXin Li portably — and correctly — in Common Lisp. 3681*8c35d5eeSXin Li You should use it when appropriate. 3682*8c35d5eeSXin Li </p> 3683*8c35d5eeSXin Li <p> 3684*8c35d5eeSXin Li First, be aware of the discrepancies between 3685*8c35d5eeSXin Li the syntax of Common Lisp pathnames, 3686*8c35d5eeSXin Li which depends on which implementation and operating system 3687*8c35d5eeSXin Li you are using, 3688*8c35d5eeSXin Li and the native syntax of pathnames on your operating system. 3689*8c35d5eeSXin Li The Lisp syntax may involves quoting of special characters 3690*8c35d5eeSXin Li such as <code>#\.</code> and <code>#\*</code>, etc., 3691*8c35d5eeSXin Li in addition to the quoting of 3692*8c35d5eeSXin Li <code>#\\</code> and <code>#\"</code> within strings. 3693*8c35d5eeSXin Li By contrast, your operating system's other 3694*8c35d5eeSXin Li system programming languages 3695*8c35d5eeSXin Li (shell, C, scripting languages) 3696*8c35d5eeSXin Li may only have one layer of quoting, into strings. 3697*8c35d5eeSXin Li </p> 3698*8c35d5eeSXin Li <p> 3699*8c35d5eeSXin Li Second, when using <code>MERGE-PATHNAMES</code>, 3700*8c35d5eeSXin Li be wary of the treatment of the <code>HOST</code> component, 3701*8c35d5eeSXin Li which matters a lot on non-Unix platforms 3702*8c35d5eeSXin Li (and even on some Unix implementations). 3703*8c35d5eeSXin Li You probably should be using 3704*8c35d5eeSXin Li <code>UIOP:MERGE-PATHNAMES*</code> or <code>UIOP:SUBPATHNAME</code> 3705*8c35d5eeSXin Li instead of <code>MERGE-PATHNAMES</code>, 3706*8c35d5eeSXin Li especially if your expectations for relative pathnames 3707*8c35d5eeSXin Li are informed by the way they work in Unix or Windows; 3708*8c35d5eeSXin Li otherwise you might hit weird bugs whereby on some implementations, 3709*8c35d5eeSXin Li merging a relative pathnames with an absolute pathname 3710*8c35d5eeSXin Li results in overriding the absolute pathname's host 3711*8c35d5eeSXin Li and replace it with the host from the value of 3712*8c35d5eeSXin Li <code>*DEFAULT-PATHNAME-DEFAULTS*</code> 3713*8c35d5eeSXin Li at the time the relative pathname was created. 3714*8c35d5eeSXin Li </p> 3715*8c35d5eeSXin Li <p> 3716*8c35d5eeSXin Li Third, be aware that <code>DIRECTORY</code> 3717*8c35d5eeSXin Li is not portable across implementations 3718*8c35d5eeSXin Li in how it handles wildcards, sub-directories, symlinks, etc. 3719*8c35d5eeSXin Li There again, <code>UIOP</code> provides several 3720*8c35d5eeSXin Li common abstractions to deal with pathnames, 3721*8c35d5eeSXin Li but only does so good a job. 3722*8c35d5eeSXin Li For a complete portable solution, use IOLib — 3723*8c35d5eeSXin Li though its Windows support lags behind. 3724*8c35d5eeSXin Li </p> 3725*8c35d5eeSXin Li <p> 3726*8c35d5eeSXin Li <code>LOGICAL-PATHNAME</code>s are not a portable abstraction, 3727*8c35d5eeSXin Li and should not be used in portable code. 3728*8c35d5eeSXin Li Many implementations have bugs in them, when they are supported at all. 3729*8c35d5eeSXin Li SBCL implements them very well, 3730*8c35d5eeSXin Li but strictly enforces the limitations on characters 3731*8c35d5eeSXin Li allowed by the standard, which restricts their applicability. 3732*8c35d5eeSXin Li Other implementations allow arbitrary characters in such pathnames, 3733*8c35d5eeSXin Li but in doing so are not being conformant, 3734*8c35d5eeSXin Li and are still incompatible with each other in many ways. 3735*8c35d5eeSXin Li You should use other pathname abstractions, 3736*8c35d5eeSXin Li such as <code>ASDF:SYSTEM-RELATIVE-PATHNAME</code> or 3737*8c35d5eeSXin Li the underlying <code>UIOP:SUBPATHNAME</code> and 3738*8c35d5eeSXin Li <code>UIOP:PARSE-UNIX-NAMESTRING</code>. 3739*8c35d5eeSXin Li </p> 3740*8c35d5eeSXin Li 3741*8c35d5eeSXin Li <p> 3742*8c35d5eeSXin Li Finally, be aware that paths may change between 3743*8c35d5eeSXin Li the time you build the Lisp image for your application, 3744*8c35d5eeSXin Li and the time you run the application from its image. 3745*8c35d5eeSXin Li You should be careful to reset your image 3746*8c35d5eeSXin Li to forget irrelevant build-time paths and 3747*8c35d5eeSXin Li reinitialize any search path from current environment variables. 3748*8c35d5eeSXin Li <code>ASDF</code> for instance requires you to reset its paths 3749*8c35d5eeSXin Li with <code>UIOP:CLEAR-CONFIGURATION</code>. 3750*8c35d5eeSXin Li <code>UIOP</code> provides hooks 3751*8c35d5eeSXin Li to call functions before an image is dumped, 3752*8c35d5eeSXin Li from which to reset or <code>makunbound</code> relevant variables. 3753*8c35d5eeSXin Li </p> 3754*8c35d5eeSXin Li 3755*8c35d5eeSXin Li </BODY> 3756*8c35d5eeSXin Li </STYLEPOINT> 3757*8c35d5eeSXin Li <STYLEPOINT title="SATISFIES"> 3758*8c35d5eeSXin Li <SUMMARY> 3759*8c35d5eeSXin Li You must be careful when using a <code>SATISFIES</code> clause in a type specifier. 3760*8c35d5eeSXin Li </SUMMARY> 3761*8c35d5eeSXin Li <BODY> 3762*8c35d5eeSXin Li <p> 3763*8c35d5eeSXin Li Most Common Lisp implementations can't optimize 3764*8c35d5eeSXin Li based on a <code>SATISFIES</code> type, 3765*8c35d5eeSXin Li but many of them offer simple optimizations 3766*8c35d5eeSXin Li based on a type of the form 3767*8c35d5eeSXin Li <code>(AND FOO (SATISFIES BAR-P))</code> 3768*8c35d5eeSXin Li where the first term of the <code>AND</code> clause 3769*8c35d5eeSXin Li describes the structure of the object 3770*8c35d5eeSXin Li without any <code>SATISFIES</code> 3771*8c35d5eeSXin Li and the second term is the <code>SATISFIES</code>. 3772*8c35d5eeSXin Li </p> 3773*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 3774*8c35d5eeSXin Li (deftype prime-number () (satisfies prime-number-p)) ; Bad 3775*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 3776*8c35d5eeSXin Li <CODE_SNIPPET> 3777*8c35d5eeSXin Li (deftype prime-number () (and integer (satisfies prime-number-p)) ; Better 3778*8c35d5eeSXin Li </CODE_SNIPPET> 3779*8c35d5eeSXin Li <p> 3780*8c35d5eeSXin Li However, <code>AND</code> in the <code>DEFTYPE</code> language 3781*8c35d5eeSXin Li isn't a left-to-right short-circuit operator 3782*8c35d5eeSXin Li as in the expression language; 3783*8c35d5eeSXin Li it is a symmetrical connector that allows for reordering subterms 3784*8c35d5eeSXin Li and doesn't guarantee short-circuiting. 3785*8c35d5eeSXin Li Therefore, in the above example, 3786*8c35d5eeSXin Li you cannot rely on the test for <code>INTEGER</code>ness 3787*8c35d5eeSXin Li to protect the function <code>PRIME-NUMBER-P</code> 3788*8c35d5eeSXin Li from being supplied non-integer arguments 3789*8c35d5eeSXin Li to test for being of instances of the type. 3790*8c35d5eeSXin Li Implementations may, and some <em>will</em>, 3791*8c35d5eeSXin Li invoke <code>SATISFIES</code>-specified function 3792*8c35d5eeSXin Li at compile-time to test various relevant objects. 3793*8c35d5eeSXin Li </p> 3794*8c35d5eeSXin Li <p> 3795*8c35d5eeSXin Li That is why any function specified in a <code>SATISFIES</code> clause 3796*8c35d5eeSXin Li MUST accept objects of any type as argument to the function, 3797*8c35d5eeSXin Li and MUST be defined within an <code>EVAL-WHEN</code> 3798*8c35d5eeSXin Li (as well as any variable it uses or function it calls): 3799*8c35d5eeSXin Li </p> 3800*8c35d5eeSXin Li <BAD_CODE_SNIPPET> 3801*8c35d5eeSXin Li (defun prime-number-p (n) ; Doubly bad! 3802*8c35d5eeSXin Li (let ((m (abs n))) 3803*8c35d5eeSXin Li (if (<= m *prime-number-cutoff*) 3804*8c35d5eeSXin Li (small-prime-number-p m) 3805*8c35d5eeSXin Li (big-prime-number-p m)))) 3806*8c35d5eeSXin Li </BAD_CODE_SNIPPET> 3807*8c35d5eeSXin Li <CODE_SNIPPET> 3808*8c35d5eeSXin Li (eval-when (:compile-toplevel :load-toplevel :execute) ; Better 3809*8c35d5eeSXin Li (defun prime-number-p (n) 3810*8c35d5eeSXin Li (when (integerp n) ; Better 3811*8c35d5eeSXin Li (let ((m (abs n))) 3812*8c35d5eeSXin Li (if (<= m *prime-number-cutoff*) 3813*8c35d5eeSXin Li (small-prime-number-p m) 3814*8c35d5eeSXin Li (big-prime-number-p m)))))) 3815*8c35d5eeSXin Li </CODE_SNIPPET> 3816*8c35d5eeSXin Li <p> 3817*8c35d5eeSXin Li In particular, the above means that the 3818*8c35d5eeSXin Li <a href="https://www.lispworks.com/documentation/HyperSpec/Body/t_satisf.htm">example</a> 3819*8c35d5eeSXin Li used in the Common Lisp Standard is erroneous: 3820*8c35d5eeSXin Li <code>(and integer (satisfies evenp))</code> 3821*8c35d5eeSXin Li is <em>not</em> a safe, conformant type specifier to use, 3822*8c35d5eeSXin Li because <code>EVENP</code> will throw an error 3823*8c35d5eeSXin Li rather than return <code>NIL</code> 3824*8c35d5eeSXin Li when passed a non-integer as an argument. 3825*8c35d5eeSXin Li </p> 3826*8c35d5eeSXin Li <p> 3827*8c35d5eeSXin Li Finally, there is a catch when your <code>DEFTYPE</code> code expands 3828*8c35d5eeSXin Li to a <code>SATISFIES</code> with a dynamically generated function: 3829*8c35d5eeSXin Li </p> 3830*8c35d5eeSXin Li <ul> 3831*8c35d5eeSXin Li <li> 3832*8c35d5eeSXin Li You cannot control when implementations will or will not 3833*8c35d5eeSXin Li expand a <code>DEFTYPE</code>. 3834*8c35d5eeSXin Li </li> 3835*8c35d5eeSXin Li <li> 3836*8c35d5eeSXin Li The expansion itself cannot contain a function definition 3837*8c35d5eeSXin Li or any code in the expression language. 3838*8c35d5eeSXin Li </li> 3839*8c35d5eeSXin Li <li> 3840*8c35d5eeSXin Li You cannot control when the expansion is used, 3841*8c35d5eeSXin Li it may happen in a different process 3842*8c35d5eeSXin Li that didn't expand the definition. 3843*8c35d5eeSXin Li </li> 3844*8c35d5eeSXin Li </ul> 3845*8c35d5eeSXin Li <p> 3846*8c35d5eeSXin Li Therefore, you cannot merely create the function 3847*8c35d5eeSXin Li as a side-effect of expansion 3848*8c35d5eeSXin Li using <code>EVAL</code> at type-expansion time. 3849*8c35d5eeSXin Li The solution is to use 3850*8c35d5eeSXin Li <code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code> instead. 3851*8c35d5eeSXin Li See the very last point 3852*8c35d5eeSXin Li in the discussion about <a href="#EVAL">EVAL</a>. 3853*8c35d5eeSXin Li </p> 3854*8c35d5eeSXin Li <p> 3855*8c35d5eeSXin Li Common Lisp is hard to satisfy. 3856*8c35d5eeSXin Li </p> 3857*8c35d5eeSXin Li </BODY> 3858*8c35d5eeSXin Li </STYLEPOINT> 3859*8c35d5eeSXin Li</CATEGORY> 3860*8c35d5eeSXin Li 3861*8c35d5eeSXin Li<HR/> 3862*8c35d5eeSXin Li 3863*8c35d5eeSXin Li<small>Credits: 3864*8c35d5eeSXin Li Adam Worrall, Dan Pierson, Matt Marjanovic, Matt Reklaitis, 3865*8c35d5eeSXin Li Paul Weiss, Scott McKay, Sundar Narasimhan, 3866*8c35d5eeSXin Li and several other people contributed. 3867*8c35d5eeSXin Li Special thanks to Steve Hain, 3868*8c35d5eeSXin Li and to the previous editors, 3869*8c35d5eeSXin Li in reverse chronological order Dan Weinreb and Jeremy Brown. 3870*8c35d5eeSXin Li</small> 3871*8c35d5eeSXin Li 3872*8c35d5eeSXin Li<p align="right"> 3873*8c35d5eeSXin LiRevision 1.28 3874*8c35d5eeSXin Li</p> 3875*8c35d5eeSXin Li 3876*8c35d5eeSXin Li 3877*8c35d5eeSXin Li<address> 3878*8c35d5eeSXin LiRobert Brown 3879*8c35d5eeSXin Li</address> 3880*8c35d5eeSXin Li 3881*8c35d5eeSXin Li<address> 3882*8c35d5eeSXin Li <a HREF="mailto:[email protected]">François-René Rideau</a> 3883*8c35d5eeSXin Li</address> 3884*8c35d5eeSXin Li 3885*8c35d5eeSXin Li 3886*8c35d5eeSXin Li 3887*8c35d5eeSXin Li</GUIDE> 3888