HACKING

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