--- /dev/null
+SBCL Hacking Guide
+
+ (This is not a most actively maintained file, but recommended
+ reading anyways.)
+
+Patch Submissions
+=================
+
+Preferred patch format is output from "git format-patch", including
+the commit message.
+
+The commit message should explain the why and how of the change. See
+existing commit messages for examples -- for a truly trivial changes
+little is needed, but in most cases more is better.
+
+Please include test-cases in your patch if at all possible: if you're
+not sure which file in tests/ to put your test case in, just pick one
+that seems vaguely appropriate.
+
+Please format your submission for ease of reading: unless the change
+is whitespace only, avoid re-indenting code you are not touching, etc.
+
+Unless your change is large and best understood as a series of
+sequential changes, please send it in as single patch.
+
+If your patch includes algorithmic changes, explain them. If your
+patch uses a published algorithm, please include a link to the paper.
+We aren't always as well-educated as we'd like to...
+
+Ready-to-apply patches should be submitted via Launchpad: please add
+the tag "review" to the associated bug (create new bug with name if
+there isn't one about the issue yet.)
+
+Patches requiring more widespread discussion and feedback should be
+sent to the sbcl-devel mailing list.
+
+If you have any questions, feel free to ask them on sbcl-devel,
+or the IRC channel #sbcl@freenode.net.
+
+Coding Style
+============
+
+See also PRINCIPLES and TLA files.
+
+Most of the style hints in the Lisp FAQ apply.
+
+When porting code we prefer code which factors dependencies into a set
+of interface functions and constants and includes implementations of
+the interface for the different systems.
+
+Reader conditionals are frowed upon. Sometimes they're the least
+of all evils, but think thrice.
+
+grammatical fussiness:
+ Phrases are not capitalized.
+ Sentences are capitalized.
+ Periods terminate sentences.
+ Periods separate phrases from succeeding sentences, e.g.
+ ;;; the maximum number of transformations we'll make before
+ ;;; concluding we're in an infinite loop and bailing. This can
+ ;;; be changed, but it is an error to change it while we're
+ ;;; solving a system.
+ (defvar *max-n-transformations* 10)
+ Lisp in comments is capitalized.
+ Symbol names are capitalized.
+
+usage fussiness:
+ Function documentation can be a description of what the function
+ does, e.g.
+ ;;; Parse the arguments for a BDEFSTRUCT call, and return
+ ;;; (VALUES NAME DEFSTRUCT-ARGS MAKE-LOAD-FORM-FUN BDEFSTRUCT-STYPE),
+ ;;; where NAME is the name of the new type, DEFSTRUCT-ARGS is the
+ ;;; munged result suitable for passing on to DEFSTRUCT,
+ ;;; MAKE-LOAD-FORM-FUN is the make load form function, or NIL if
+ ;;; there's none, and BDEFSTRUCT-SUPERTYPE is the direct supertype
+ ;;; of the type if it is another BDEFSTRUCT-defined type, or NIL
+ ;;; otherwise.
+ (defun parse-bdefstruct-args (nameoid &rest rest)
+ ..)
+ or a remark about the function, e.g.
+ ;;; a helper function for BDEFSTRUCT in the #+XC-HOST case
+ (defun uncross-defstruct-args (defstruct-args)
+ ..)
+ If you're talking about what the function does, ordinarily you
+ should just say what the function does, e.g.
+ ;;; Return the first prime number greater than or equal to X.
+ (defun primify (x) ..)
+ instead of telling the reader that you're going to tell him what
+ the function does, e.g.
+ ;;; PRIMIFY returns the first prime number greater than or
+ ;;; equal to X.
+ (defun primify (x) ..)
+ or
+ ;;; When you call this function on X, you get back the first
+ ;;; prime number greater than or equal to X.
+ (defun primify (x) ..)
+ Documentation for public functions belongs in a docstring.
+ Documentation for internal functions belongs mostly in a comment.
+
+In general, if you can express it in the code instead of the comments,
+do so. E.g. the old CMUCL code has many comments above functions foo
+that say things like
+ ;;; FOO -- interface
+If we were going to do something like that, we would prefer to do it by
+writing
+ (EXPORT 'FOO)
+(Instead, for various other reasons, we centralize all the exports
+in package declarations.) The old "FOO -- interface" comments are bad
+style because they duplicate information (and they illustrate one
+of the evils of duplicating information by the way that they have
+drifted out of sync with the code).
+
+There are a number of style practices on display in the code
+which are not good examples to follow:
+ * using conditional compilation to support different architectures,
+ instead of factoring the dependencies into interfaces and providing
+ implementations of the interface for different architectures;
+ * in conditional compilation, using a common subexpression over and
+ over again, e.g. #+(OR X86 X86-64), when the important thing is
+ that the platform supports single-instruction CAS. If you have to
+ do something like that, define a new FOO feature, write #+FOO in
+ many places, and arrange for the FOO feature to be set once and
+ only once -- probably in make-config.sh. (That way future
+ maintainers won't curse you.)
+ * putting the defined symbol, and information about whether it's
+ exported or not, into the comments around the definition of the symbol;
+ * naming anything DO-FOO if it isn't an iteration macro
+ * not using a consistent abbreviation style in global names (e.g.
+ naming some things DEFINE-FOO and other things DEF-BAR, with
+ no rule to determine whether the abbreviation is used).
+ * using lots of single-colon package prefixes (distracting and hard
+ to read, and obstacles to reaching package nirvana where
+ package dependencies are a directed acyclic graph) or even
+ double-colon package prefixes (hard to understand and hard
+ to maintain). (One exception: I've sometimes been tempted to
+ add a CL: prefix to the definition of every CL symbol (e.g.
+ (DEFUN CL:CADDDR (..) ..) as reminders that they're required by
+ ANSI and can't be deleted no matter how obscure and useless some
+ of them might look.:-)
+Many of these are common in the code inherited from CMUCL. We've
+eliminated them in some places, but there's a *lot* of code inherited
+from CMUCL..
projects / sbcl.git / blobdiff