STYLE

   1 Most of the style hints in the Lisp FAQ apply.
   2
   3 When porting the system, I would really prefer code which factors
   4 dependencies into a set of interface functions and constants and
   5 includes implementations of the interface for the different systems.
   6 Patches which require conditional compilation (like all the old
   7 #T+HPUX or #T-X86 tests in the sources inherited from CMUCL) might be
   8 accepted if they're simple, in hopes of factoring out the differences
   9 more cleanly later, but even if accepted, such code may not be
  10 maintained for very long.
  11
  12 grammatical fussiness:
  13   Phrases are not capitalized.
  14   Sentences are capitalized.
  15   Periods terminate sentences.
  16   Periods separate phrases from succeeding sentences, e.g.
  17     ;;; the maximum number of transformations we'll make before
  18     ;;; concluding we're in an infinite loop and bailing. This can
  19     ;;; be changed, but it is an error to change it while we're
  20     ;;; solving a system.
  21     (defvar *max-n-transformations* 10)
  22   Lisp in comments is capitalized.
  23
  24 usage fussiness:
  25   Function documentation can be a description of what the function
  26     does, e.g.
  27         ;;; Parse the arguments for a BDEFSTRUCT call, and return
  28         ;;;   (VALUES NAME DEFSTRUCT-ARGS MAKE-LOAD-FORM-FUN BDEFSTRUCT-STYPE),
  29         ;;; where NAME is the name of the new type, DEFSTRUCT-ARGS is the
  30         ;;; munged result suitable for passing on to DEFSTRUCT,
  31         ;;; MAKE-LOAD-FORM-FUN is the make load form function, or NIL if
  32         ;;; there's none, and BDEFSTRUCT-SUPERTYPE is the direct supertype
  33         ;;; of the type if it is another BDEFSTRUCT-defined type, or NIL
  34         ;;; otherwise.
  35         (defun parse-bdefstruct-args (nameoid &rest rest)
  36           ..)
  37     or a remark about the function, e.g.
  38         ;;; a helper function for BDEFSTRUCT in the #+XC-HOST case
  39         (defun uncross-defstruct-args (defstruct-args)
  40           ..)
  41     If you're talking about what the function does, ordinarily you
  42     should just say what the function does, e.g.
  43         ;;; Return the first prime number greater than or equal to X.
  44         (defun primify (x) ..)
  45     instead of telling the reader that you're going to tell him what
  46     the function does, e.g.
  47         ;;; PRIMIFY returns the first prime number greater than or
  48         ;;; equal to X.
  49         (defun primify (x) ..)
  50     or
  51         ;;; When you call this function on X, you get back the first
  52         ;;; prime number greater than or equal to X.
  53         (defun primify (x) ..)
  54
  55 In general, if you can express it in the code instead of the comments,
  56 do so. E.g. the old CMUCL code has many comments above functions foo
  57 that say things like
  58         ;;; FOO -- interface
  59 If we were going to do something like that, we would prefer to do it by
  60 writing
  61         (EXPORT 'FOO)
  62 (Instead, for various other reasons, we centralize all the exports
  63 in package declarations.) The old "FOO -- interface" comments are bad
  64 style because they duplicate information (and they illustrate one
  65 of the evils of duplicating information by the way that they have
  66 drifted out of sync with the code).
  67
  68 There are a number of style practices on display in the code
  69 which are not good examples to follow:
  70   * using conditional compilation to support different architectures,
  71     instead of factoring the dependencies into interfaces and providing
  72     implementations of the interface for different architectures;
  73   * in conditional compilation, using a common subexpression over and
  74     over again, e.g. #+(OR GENGC GENCGC), when the important thing is
  75     that GENGC and GENCGC are (currently) the GCs which support scavenger
  76     hooks. If you have to do that, define a SCAVHOOK feature,
  77     write #+SCAVHOOK in many places, and arrange for the SCAVHOOK feature
  78     to be set once and only once in terms of GENGC and GENCGC. (That way
  79     future maintainers won't curse you.)
  80   * putting the defined symbol, and information about whether it's
  81     exported or not, into the comments around the definition of the symbol;
  82   * naming anything DO-FOO if it isn't an iteration macro
  83   * exposing a lot of high-level functionality not in the ANSI standard
  84     to the user (as discussed above)
  85   * not using a consistent abbreviation style in global names (e.g.
  86     naming some things DEFINE-FOO and other things DEF-BAR, with
  87     no rule to determine whether the abbreviation is used)
  88   * using lots of single-colon package prefixes (distracting and hard
  89     to read, and obstacles to reaching package nirvana where
  90     package dependencies are a directed acyclic graph) or even
  91     double-colon package prefixes (hard to understand and hard
  92     to maintain). (One exception: I've sometimes been tempted to
  93     add a CL: prefix to the definition of every CL symbol (e.g.
  94     (DEFUN CL:CADDDR (..) ..) as reminders that they're required by
  95     ANSI and can't be deleted no matter how obscure and useless some
  96     of them might look.:-)
  97 Most of these are common in the code inherited from CMUCL. I've
  98 eliminated them in some places, but there's a *lot* of code inherited
  99 from CMUCL..