STYLE

   1 SBCL Style Guide
   2
   3   (This is not a most actively maintained file, but recommended
   4   reading anyways.)
   5
   6 Patch Submissions
   7 =================
   8
   9 Preferred patch format is output from "git format-patch", including
  10 the commit message. The commit message should explain the why and how
  11 of the change.
  12
  13 Please include test-cases in your patch if at all possible.
  14
  15 Please format your submission for ease of reading: unless the change
  16 is whitespace only, avoid re-indenting code you are not touching, etc.
  17 Unless your patch is large and best understood as a series of
  18 sequential changes, please send it in as single patch file.
  19
  20 If your patch includes algorithmic changes, explain them. If your
  21 patch uses a published algorithm, please include a link to the paper.
  22 We aren't always as well-educated as we'd like to...
  23
  24 Ready-to-apply patches should be submitted via Launchpad: please add
  25 the tag "review" to the associated bug.
  26
  27 Patches requiring more widespread discussion and feedback should be
  28 sent to the sbcl-devel mailing list.
  29
  30 If you have any questions, feel free to ask them on sbcl-devel.
  31
  32 Coding Style
  33 ============
  34
  35 See also PRINCIPLES and TLA files.
  36
  37 Most of the style hints in the Lisp FAQ apply.
  38
  39 When porting code we prefer code which factors dependencies into a set
  40 of interface functions and constants and includes implementations of
  41 the interface for the different systems. Patches which require
  42 conditional compilation (like all the old
  43 #T+HPUX or #T-X86 tests in the sources inherited from CMUCL) might be
  44 accepted if they're simple, in hopes of factoring out the differences
  45 more cleanly later, but even if accepted, such code may not be
  46 maintained for very long.
  47
  48 grammatical fussiness:
  49   Phrases are not capitalized.
  50   Sentences are capitalized.
  51   Periods terminate sentences.
  52   Periods separate phrases from succeeding sentences, e.g.
  53     ;;; the maximum number of transformations we'll make before
  54     ;;; concluding we're in an infinite loop and bailing. This can
  55     ;;; be changed, but it is an error to change it while we're
  56     ;;; solving a system.
  57     (defvar *max-n-transformations* 10)
  58   Lisp in comments is capitalized.
  59
  60 usage fussiness:
  61   Function documentation can be a description of what the function
  62     does, e.g.
  63         ;;; Parse the arguments for a BDEFSTRUCT call, and return
  64         ;;;   (VALUES NAME DEFSTRUCT-ARGS MAKE-LOAD-FORM-FUN BDEFSTRUCT-STYPE),
  65         ;;; where NAME is the name of the new type, DEFSTRUCT-ARGS is the
  66         ;;; munged result suitable for passing on to DEFSTRUCT,
  67         ;;; MAKE-LOAD-FORM-FUN is the make load form function, or NIL if
  68         ;;; there's none, and BDEFSTRUCT-SUPERTYPE is the direct supertype
  69         ;;; of the type if it is another BDEFSTRUCT-defined type, or NIL
  70         ;;; otherwise.
  71         (defun parse-bdefstruct-args (nameoid &rest rest)
  72           ..)
  73     or a remark about the function, e.g.
  74         ;;; a helper function for BDEFSTRUCT in the #+XC-HOST case
  75         (defun uncross-defstruct-args (defstruct-args)
  76           ..)
  77     If you're talking about what the function does, ordinarily you
  78     should just say what the function does, e.g.
  79         ;;; Return the first prime number greater than or equal to X.
  80         (defun primify (x) ..)
  81     instead of telling the reader that you're going to tell him what
  82     the function does, e.g.
  83         ;;; PRIMIFY returns the first prime number greater than or
  84         ;;; equal to X.
  85         (defun primify (x) ..)
  86     or
  87         ;;; When you call this function on X, you get back the first
  88         ;;; prime number greater than or equal to X.
  89         (defun primify (x) ..)
  90
  91 In general, if you can express it in the code instead of the comments,
  92 do so. E.g. the old CMUCL code has many comments above functions foo
  93 that say things like
  94         ;;; FOO -- interface
  95 If we were going to do something like that, we would prefer to do it by
  96 writing
  97         (EXPORT 'FOO)
  98 (Instead, for various other reasons, we centralize all the exports
  99 in package declarations.) The old "FOO -- interface" comments are bad
 100 style because they duplicate information (and they illustrate one
 101 of the evils of duplicating information by the way that they have
 102 drifted out of sync with the code).
 103
 104 There are a number of style practices on display in the code
 105 which are not good examples to follow:
 106   * using conditional compilation to support different architectures,
 107     instead of factoring the dependencies into interfaces and providing
 108     implementations of the interface for different architectures;
 109   * in conditional compilation, using a common subexpression over and
 110     over again, e.g. #+(OR GENGC GENCGC), when the important thing is
 111     that GENGC and GENCGC are (currently) the GCs which support scavenger
 112     hooks. If you have to do that, define a SCAVHOOK feature,
 113     write #+SCAVHOOK in many places, and arrange for the SCAVHOOK feature
 114     to be set once and only once in terms of GENGC and GENCGC. (That way
 115     future maintainers won't curse you.)
 116   * putting the defined symbol, and information about whether it's
 117     exported or not, into the comments around the definition of the symbol;
 118   * naming anything DO-FOO if it isn't an iteration macro
 119   * exposing a lot of high-level functionality not in the ANSI standard
 120     to the user (as discussed above)
 121   * not using a consistent abbreviation style in global names (e.g.
 122     naming some things DEFINE-FOO and other things DEF-BAR, with
 123     no rule to determine whether the abbreviation is used)
 124   * using lots of single-colon package prefixes (distracting and hard
 125     to read, and obstacles to reaching package nirvana where
 126     package dependencies are a directed acyclic graph) or even
 127     double-colon package prefixes (hard to understand and hard
 128     to maintain). (One exception: I've sometimes been tempted to
 129     add a CL: prefix to the definition of every CL symbol (e.g.
 130     (DEFUN CL:CADDDR (..) ..) as reminders that they're required by
 131     ANSI and can't be deleted no matter how obscure and useless some
 132     of them might look.:-)
 133 Most of these are common in the code inherited from CMUCL. We've
 134 eliminated them in some places, but there's a *lot* of code inherited
 135 from CMUCL..