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