diff --git a/lispguide.xml b/lispguide.xml index acc6219..f566315 100644 --- a/lispguide.xml +++ b/lispguide.xml @@ -5,7 +5,7 @@

-Revision 1.20 +Revision 1.22

@@ -180,7 +180,7 @@ Robert Brown

Some of these guidelines are motivated by universal principles of good programming. Some guidelines are motivated by technical peculiarities of Common Lisp. - Some guidelines where once motivated by a technical reason, + Some guidelines were once motivated by a technical reason, but the guideline remained after the reason subsided. Some guidelines, such those about as comments and indentation, are based purely on convention, rather than on clear technical merit. @@ -211,15 +211,22 @@ Robert Brown -

- A lot of our code was written before these guidelines existed. - You should fix violations as you encounter them - in the course of your normal coding. - You must not fix violations en masse - without warning other developers and coordinating with them, - so as not to make the merging of large branches - more difficult than it already is. -

+ + Fix old code as you go. + + +

+ A lot of our code was written before these guidelines existed. + You should fix violations as you encounter them + in the course of your normal coding. +

+

+ You must not fix violations en masse + without warning other developers and coordinating with them, + so as not to make the merging of large branches + more difficult than it already is. +

+ @@ -514,11 +521,11 @@ Robert Brown without any compilation error or warning messages whatsoever. If the compiler issues warnings that should be ignored, muffle those warnings using the - xcvb-driver:with-controlled-compiler-conditions and - xcvb-driver:*uninteresting-conditions* - framework (also available as asdf-condition-control), + UIOP:WITH-MUFFLED-COMPILER-CONDITIONS and + UIOP:*UNINTERESTING-COMPILER-CONDITIONS* + framework (part of UIOP, part of ASDF 3), either around the entire project, or around individual files - (using asdf's :around-compile hooks). + (using ASDF's :around-compile hooks).
  • All code should be checked in an appropriate source control system, @@ -549,7 +556,7 @@ Robert Brown - +

    You must use correct spelling in your comments, @@ -717,7 +724,7 @@ Robert Brown After that in-package form, every file should follow with any file-specific (declaim (optimize ...)) declaration - that is not covered by an asdf :around-compile hook. + that is not covered by an ASDF :around-compile hook.

    ;;;; Author: brown (Robert Brown) @@ -1169,7 +1176,7 @@ Robert Brown You should use lower case. - You should follow the rules for Spelling and Abbreviations + You should follow the rules for Spelling and Abbreviations You should follow punctuation conventions. @@ -1202,9 +1209,9 @@ Robert Brown unless you have a well-documented overarching reason to, and permission from other hackers who review your proposal.

    - See the section on Spelling and Abbreviations - for guidelines on using abbreviations.

    + See the section on Spelling and Abbreviations + for guidelines on using abbreviations.

    ;; Bad @@ -2415,7 +2422,7 @@ Robert Brown

    • - Implementing an interactive development loop. + The implementation of an interactive development tool.
    • The build infrastructure. @@ -3282,7 +3289,7 @@ Robert Brown More generally, unsafe operations will yield the correct result faster than would the equivalent safe operation - if the arguments to satisfy some invariant such as + if the arguments satisfy some invariant such as being of the correct type and small enough; however if the arguments fail to satisfy the required invariants, then the operation may have undefined behavior, @@ -3293,8 +3300,8 @@ Robert Brown or whether it is accounting for large amounts money, such undefined behavior can kill or bankrupt people. Yet proper speed can sometimes make the difference between - software that's unusably slow and software that does its job; - between software that is a net loss + software that's unusably slow and software that does its job, + or between software that is a net loss and software that can yield a profit.

      @@ -3330,6 +3337,7 @@ Robert Brown but is not to be used for production code since it defeats the purpose of declarations as a performance trick.

      + @@ -3486,9 +3494,12 @@ Robert Brown when an appropriate implementation is only O(n). Moreover, (REDUCE 'APPEND ...) is also O(n^2) unless you specify :FROM-END T. - In such cases, you must use proper abstractions - that cover those cases instead of calling REDUCE, - first defining them in a suitable library if need be. + In such cases, you MUST NOT use REDUCE, + but instead you MUST use proper abstractions + from a suitable library (that you may have to contribute to) + that properly handles those cases + without burdening users with implementation details. + See for instance UIOP:REDUCE/STRCAT.

      @@ -3620,12 +3631,18 @@ Robert Brown       - Common Lisp pathnames are tricky. Be aware of pitfalls. + Common Lisp pathnames are tricky. Be aware of pitfalls. Use UIOP.

      It is surprisingly hard to properly deal with pathnames in Common Lisp.

      +

      + ASDF 3 comes with a portability library UIOP + that makes it much easier to deal with pathnames + portably — and correctly — in Common Lisp. + You should use it when appropriate. +

      First, be aware of the discrepancies between the syntax of Common Lisp pathnames, @@ -3647,7 +3664,7 @@ Robert Brown which matters a lot on non-Unix platforms (and even on some Unix implementations). You probably should be using - ASDF-UTILS:MERGE-PATHNAMES* + UIOP:MERGE-PATHNAMES* instead of MERGE-PATHNAMES, especially if your expectations for relative pathnames are informed by the way they work in Unix or Windows; @@ -3662,7 +3679,7 @@ Robert Brown Third, be aware that DIRECTORY is not portable across implementations in how it handles wildcards, sub-directories, symlinks, etc. - There again, ASDF-UTILS provides several + There again, UIOP provides several common abstractions to deal with pathnames.

      @@ -3671,13 +3688,14 @@ Robert Brown Many implementations have bugs in them, when they are supported at all. SBCL implements them very well, but strictly enforces the limitations on characters - allowed by the standard. + allowed by the standard, which restricts their applicability. Other implementations allow arbitrary characters in such pathnames, but in doing so are not being conformant, and are still incompatible with each other in many ways. You should use other pathname abstractions, such as ASDF:SYSTEM-RELATIVE-PATHNAME or - the underlying ASDF-UTILS:COERCE-PATHNAME. + the underlying UIOP:SUBPATHNAME and + UIOP:PARSE-UNIX-NAMESTRING.

      @@ -3689,6 +3707,9 @@ Robert Brown reinitialize any search path from current environment variables. ASDF for instance requires you to reset its paths with ASDF:CLEAR-CONFIGURATION. + UIOP provides hooks + to call functions before an image is dumped, + from which to reset or makunbound relevant variables.

      @@ -3808,7 +3829,7 @@ Robert Brown

      -Revision 1.20 +Revision 1.22