STYLE: Make this document cover multiple languages.
[sod] / STYLE
diff --git a/STYLE b/STYLE
index a6a4f5c..49ad150 100644 (file)
--- a/STYLE
+++ b/STYLE
@@ -1,6 +1,35 @@
-Notes on Lisp style
+Notes on coding style
 
 
-* Language subset and extensions
+* General
+
+** Layout
+
+Lines are 77 characters at most, except for strange special effects.
+Don't ask.  This is not negotiable, though.  Don't try to tell me that
+your monitor is very wide so you can read longer lines.  My monitor is
+likely at least as wide.  On the other hand, most lines are easily short
+enough to fit in my narrow columns, so the right hand side of a wide
+window would be mostly blank.  This seems wasteful to me, when I could
+fill that space with more code.
+
+Horizontal whitespace for layout purposes -- i.e., indentation and
+alignment, rather than just separating words -- consists of as many tabs
+as possible, followed by as many spaces as necessary to reach the target
+column.  Tab stops occur at every eight columns.  You can tell this
+because when you cat a file to your terminal, that's how the tabs
+appear.  Editors which disagree about this are simply wrong.
+
+My indentation quantum is usually two columns.  It seems that some
+modern editors are deeply confused, and think that tab width and
+indentation quantum are the same thing, but they aren't.  Such broken
+editors will make a hopeless mess of my code.  If you have the
+misfortune to use such an editor, maybe you could contribute patches to
+fix it.
+
+
+* Lisp style
+
+** Language subset and extensions
 
 None of ANSI Common Lisp is off-limits.
 
 
 None of ANSI Common Lisp is off-limits.
 
@@ -53,8 +82,7 @@ suite, which makes additional use of ~xlunit~.  Running the test suite
 isn't essential to getting the translator built, so this isn't as much
 of a problem.
 
 isn't essential to getting the translator built, so this isn't as much
 of a problem.
 
-
-* Layout
+** Layout
 
 I pretty much let Emacs indent my code for me, based on information
 collected by SLIME.  Some exceptions:
 
 I pretty much let Emacs indent my code for me, based on information
 collected by SLIME.  Some exceptions:
@@ -90,28 +118,6 @@ collected by SLIME.  Some exceptions:
     mandatory positional arguments that I had to split them.  So far,
     this situation hasn't come up.
 
     mandatory positional arguments that I had to split them.  So far,
     this situation hasn't come up.
 
-Lines are 77 characters at most, except for strange special effects.
-Don't ask.  This is not negotiable, though.  Don't try to tell me that
-your monitor is very wide so you can read longer lines.  My monitor is
-likely at least as wide.  On the other hand, most lines are easily short
-enough to fit in my narrow columns, so the right hand side of a wide
-window would be mostly blank.  This seems wasteful to me, when I could
-fill that space with more code.
-
-Horizontal whitespace for layout purposes -- i.e., indentation and
-alignment, rather than just separating words -- consists of as many tabs
-as possible, followed by as many spaces as necessary to reach the target
-column.  Tab stops occur at every eight columns.  You can tell this
-because when you cat a file to your terminal, that's how the tabs
-appear.  Editors which disagree about this are simply wrong.
-
-My indentation quantum is usually two columns.  It seems that some
-modern editors are deeply confused, and think that tab width and
-indentation quantum are the same thing, but they aren't.  Such broken
-editors will make a hopeless mess of my code.  If you have the
-misfortune to use such an editor, maybe you could contribute patches to
-fix it.
-
 Lisp code does have a tendency to march across to the right quite
 rapidly given a chance.  I have a number of strategies for dealing with
 this.
 Lisp code does have a tendency to march across to the right quite
 rapidly given a chance.  I have a number of strategies for dealing with
 this.
@@ -126,8 +132,7 @@ this.
   + Shrug my shoulders and let code dribble down the right hand side for
     a bit.
 
   + Shrug my shoulders and let code dribble down the right hand side for
     a bit.
 
-
-* Packages and exporting
+** Packages and exporting
 
 A package collects symbols which are given meanings in one or more
 source files.  If a package's code is all in one file, then the package
 
 A package collects symbols which are given meanings in one or more
 source files.  If a package's code is all in one file, then the package
@@ -159,8 +164,7 @@ See ~doc/list-symbols.lisp~ for more sophisticated reporting.  (In
 particular, this identifies what kind of thing(s) each external symbol
 names.)
 
 particular, this identifies what kind of thing(s) each external symbol
 names.)
 
-
-* Comments and file structuring
+** Comments and file structuring
 
 A file starts with a big ~;;;~ comment bearing the Emacs ~-*-lisp-*-~
 marker, a quick description, and copyright and licensing boilerplate.  I
 
 A file starts with a big ~;;;~ comment bearing the Emacs ~-*-lisp-*-~
 marker, a quick description, and copyright and licensing boilerplate.  I
@@ -212,8 +216,7 @@ Files end, as a result of long tradition, with a comment
 
 : ;;;----- That's all, folks --------------------------------------------------
 
 
 : ;;;----- That's all, folks --------------------------------------------------
 
-
-* Macro style
+** Macro style
 
 I don't mind complicated macros if they're doing something worthwhile.
 They need to have good documentation strings, though.
 
 I don't mind complicated macros if they're doing something worthwhile.
 They need to have good documentation strings, though.
@@ -226,8 +229,7 @@ It's extremely bad taste for a macro to evaluate its evaluable
 parameters in any order other than strictly left to right, or to
 evaluate them more than once.
 
 parameters in any order other than strictly left to right, or to
 evaluate them more than once.
 
-
-* Data structures
+** Data structures
 
 I've tended to be happy with plain lists for homogeneous-ish
 collections.  Strongly heterogeneous collections (other than input
 
 I've tended to be happy with plain lists for homogeneous-ish
 collections.  Strongly heterogeneous collections (other than input
@@ -283,8 +285,7 @@ making a new structure type.  I tend to tidy up a few rough edges.
     to roll up your sleeves and mess with ~&aux~ parameters to pull it
     off.
 
     to roll up your sleeves and mess with ~&aux~ parameters to pull it
     off.
 
-
-* Naming
+** Naming
 
 I'm a traditionalist in some ways, and one of the reasons I like Lisp is
 the richness of its history and tradition.
 
 I'm a traditionalist in some ways, and one of the reasons I like Lisp is
 the richness of its history and tradition.
@@ -306,8 +307,7 @@ with the same intention, and the bindings are then explicitly ignored
 with a declaration.  The names begin ~hunoz~, ~hukairz~, and (I think)
 ~huaskt~.
 
 with a declaration.  The names begin ~hunoz~, ~hukairz~, and (I think)
 ~huaskt~.
 
-
-* Declarations
+** Declarations
 
 The code is light on declarations, other than ~ignore~ and similar used
 to muffle warnings.  The macros try to do sensible things with
 
 The code is light on declarations, other than ~ignore~ and similar used
 to muffle warnings.  The macros try to do sensible things with