STYLE: Make this document cover multiple languages.

[sod] / STYLE

Notes on coding style

* 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.

I think my Lisp style is rather more imperative in flavour than most
modern Lisp programmers.  It's probably closer to historical Lisp
practice in that regard, even though I wasn't writing Lisp back then.  A
lot of this is because I don't assume that the Lisp implementation
handles tail calls properly: Common Lisp is not Scheme.

I make extensive use of CLOS, and macros.  On a couple of occasions I've
made macros which use CLOS generic function dispatch to compute their
expansions.  The parser language is probably the best example of this in
the codebase.

I like hairy ~format~ strings.  I've intentionally opted to leave them
as challenges to the reader rather than explain them.

I've avoided hairy ~loop~ for the most part, not because I dislike it
strongly but because others do and I don't find that it wins big enough
for the fight to be worthwhile.

I only use ~&aux~ lambda-list parameters in ~defstruct~ BOA
constructors, for special effects.

I use ~car~, not ~first~, and ~cdr~, not ~rest~.  Similarly, I use
~cadr~, not ~second~, and I'm not afraid to use ~cddr~ or ~cadar~.

Similarly, I've not used ~elt~, preferring to know what kind of sequence
I'm dealing with, or using the built-in sequence functions.

I'm happy to use ~1+~, and I like the brevity of ~1-~ enough to use it
despite its terrible name.

There are no reader syntax extensions in the code.  This is because I
couldn't think of any way they'd be especially helpful, and not because
I'm in any way opposed to them.

The main translator, in the ~SOD~ package, tries to assume very little
beyond ANSI Common Lisp and what's included in just about every serious
implementation: specifically, MOP introspection, and Gray streams.
There's intentionally no MOP intercession.

The frontend additionally makes use of ~cl-launch~, but the dependency
is actually quite weak, and it could be replaced with a different, maybe
implementation-specific, mechanism fairly easily.  I'm keen to take
patches which improve frontend portability.

I'm more tolerant of extensions and external dependencies in the test
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.

** Layout

I pretty much let Emacs indent my code for me, based on information
collected by SLIME.  Some exceptions:

  + DSLs (e.g., the parser language) have their own space of macros
    which Emacs doesn't understand and for the most part I haven't
    bothered to teach it.

  + Emacs sometimes does a bad job with hairy ~loop~ and requires manual
    fixing.  Since I don't use hairy ~loop~ much, this isn't a major
    problem.

  + Emacs indents lambda lists really badly.  I often prefer to put the
    entire lambda list on its own line than to split it.  If I have to
    split a simple lambda list, without lambda-list keywords, I just
    align the start of each subsequent line with the start of the first
    argument.  I break hairy lambda lists before lambda-list keywords,
    and the start of a subsequent line aligns with the first argument
    name following the lambda-list keyword which begins the group, so
    that the lambda-list keyword stands out.

    : (defun many-arguments (first second third
    : 			     fourth fifth)
    :   ...)

    : (defun hairy-arguments (first second third
    : 			      &optional fourth fifth
    : 					sixth
    : 			      &rest others)
    :   ...)

    I don't know what I'd do if I had a hairy lambda list with so many
    mandatory positional arguments that I had to split them.  So far,
    this situation hasn't come up.

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.

  + Break a long nested calculation into pieces, giving names to the
    intermediate results, in a ~let*~ form.

  + Hoist deeply nested complex computations out into ~flet~ or
    ~labels~, and then invoke them from inside whatever complicated
    conditional mess was needed to decide what to do.

  + Shrug my shoulders and let code dribble down the right hand side for
    a bit.

** 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
definition can be put in that file too; otherwise I put it in its own
file.

I don't put ~:export~ in package definitions.  Instead, I scatter calls
to the ~export~ function throughout the code, right next to where the
relevant symbol is defined.  This has three important advantages.

  + You can tell, when you're reading the code which defines ~foo~,
    whether ~foo~ is exported and therefore a defined part of the
    package interface.

  + When you know that you're writing a thing which will form part of
    the package interface, you don't have to go off and edit some other
    file to export it.

  + A master list of exported symbols becomes a merge hazard: if two
    different branches add symbols to nearby pieces of the master list
    then you get a merge conflict for no especially good reason.

There's an apparent disadvantage: there's no immediately visible master
list of exported symbols.  But that's not a big problem:

: (loop for s being the external-symbols of pkg collect s)

See ~doc/list-symbols.lisp~ for more sophisticated reporting.  (In
particular, this identifies what kind of thing(s) each external symbol
names.)

** 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
don't use four-semicolon comments, and I only use ~#|~ ... ~|#~ for
special effects.

Then there's package stuff.  There may be a ~cl:defpackage~ form (with
explicit package qualifier) if the relevant package doesn't have its own
package definition file.  I use gensyms to name packages: strings don't
seem right, and symbols would leak into some unrelated package.

Then there's ~cl:in-package~.  Like ~defpackage~, I use a gensym to name
the package.  I can't think offhand of a good reason to have a file with
sections `in' more than one package.  So, the ~in-package~ form goes at
the top of the file, before the first section header.  If sections are
going to end up in separate packages, I think I'd put a ~cl:in-package~
at the top of each section in case I wanted to reorder them.

The rest of the file consists of Lisp code.  I don't use page boundaries
~^L~ to split files up.  Instead, I use big banner comments for this:

: ;;;--------------------------------------------------------------------------
: ;;; Section title.

Sections don't usually have internal comments, but if they did they'd
also be ~;;;~ comments.

Almost all definitions get documentation strings.  I've tried to be
consistent about formatting.

  + Docstring lines are 77 characters or less.

  + The first line gives a summary of what the thing does.  The summary,
    together with the SLIME-generated synopsis, is likely enough to
    remind you what the thing does.

  + The rest of the lines are indented by three spaces, and explain
    carefully what the thing does and what all the parameters mean.

Smallish functions and macros don't usually need any further
commentary.  Big functions often need to be split into bitesize pieces
with their own internal ~;;~ comments.  The idea is that these comments
should explain the code's overall strategy to the reader, and help them
figure out how a piece fits into that strategy.

Winged, single ~;~ comments are very rare.

Files end, as a result of long tradition, with a comment

: ;;;----- That's all, folks --------------------------------------------------

** Macro style

I don't mind complicated macros if they're doing something worthwhile.
They need to have good documentation strings, though.

That said, where possible I've tried to factor macros into an actual
macro providing the syntactic sugar, and a function which receives the
parameters and $\eta$-expanded forms, and does the actual work.

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.

** Data structures

I've tended to be happy with plain lists for homogeneous-ish
collections.  Strongly heterogeneous collections (other than input
syntax, destructured using ~defmacro~ or ~destructuring-bind~) I've
tended to make a proper data type for.

My first instinct when defining a new structure is to use ~defclass~.
While it's annoyingly verbose, it has the immense benefit over
~defstruct~ that it's safe to redefine CLOS classes in a running image
without the world breaking, and I usually find it necessary to add or
change slots while I'm working on new code.  Once a piece of code has
settled down and I have a good feel for what my structure is actually
doing, I might switch the ~defclass~ for a ~defstruct~.  Several
questions influence my decision.

  + Do slot accesses need to be really fast?  My usual Lisp
    implementations aggressively optimize ~defstruct~ accessor
    functions.

  + Have I subclassed my class?  While I can move over a
    single-inheritance tree using ~:include~, it seems wrong to do this
    most of the time.  Also, I'd be precluding subclasses from multiple
    inheritance, and I'd either have to prohibit subclassing by
    extensions or have to commit to ~defstruct~ in the documentation.
    In general, I'm much happier committing to ~defclass~.

  + Are there methods specialized on my class?  Again, structure classes
    make fine method specializers, but it doesn't seem right.

Apart from being hard to redefine, ~defstruct~ does a pretty good job of
making a new structure type.  I tend to tidy up a few rough edges.

  + The default predicate always has ~-p~ appended.  If the class name
    is a single word, then I'll explicitly name the predicate with a
    simple ~p~ suffix.  For example, ~ship~ would have the predicate
    ~shipp~, rather than ~ship-p~.

  + If there are slots I can't default then I'll usually provide a BOA
    constructor which sets them from required parameters; other slots
    I'll set from optional or keyword parameters according to my taste
    and judgement.

  + Slots mustn't be given names which are external in any package.
    Unfortunately, slot names are used in constructing accessor names,
    and sometimes the right accessor name involves a prohibited symbol.
    I've mostly addressed this by naming the slot ~%foo~, and then
    providing inline reader and writer functions.  (CLOS class
    definitions don't have this problem because you get to set the
    accessor function names independently of the slot names.)

  + BOA constructors are strange.  You can set the initial slots based
    on an arbitrary computation on the provided parameters, but you have
    to roll up your sleeves and mess with ~&aux~ parameters to pull it
    off.

** Naming

I'm a traditionalist in some ways, and one of the reasons I like Lisp is
the richness of its history and tradition.

In other languages, I tend to use single- or two-letter names for
variables and structure slots; not so much in Lisp.  Other languages
express more using punctuation, so the names stand out easily; I find
that short names can be lost more easily in Lisp.

I've also tended to go for fairly prosaic names, taking my inspiration
from the CLOS MOP.  While I mourn the loss of whimsical names like
~haulong~ and ~haipart~, I've tried to avoid inventing more of them.

There's a convention, which I think comes from ML, of using ~_~ where a
binding occurrence of a variable name is expected, to signify that that
the corresponding value is to be discarded.  Common Lisp, alas, doesn't
have such a convention.  Instead, there's a sequence of silly names used
with the same intention, and the bindings are then explicitly ignored
with a declaration.  The names begin ~hunoz~, ~hukairz~, and (I think)
~huaskt~.

** Declarations

The code is light on declarations, other than ~ignore~ and similar used
to muffle warnings.  The macros try to do sensible things with
declarations, and I think they succeed fairly well, but there might be
bugs and rough edges.  I know that some are just broken because, for
actual correctness, declarations provided by the caller need to be split
up into a number of different parts of the expansion, which in turn
requires figuring out what the declarations mean and which bindings
they're referring to.  That's not completely impossible, assuming that
there aren't implementation-specific declarations with crazy syntax
mixed in there, but it's more work than seems worthwhile.


* COMMENT Emacs cruft

#+LATEX_CLASS: strayman

## LocalWords:  CLOS ish destructure destructured accessor specializers
## LocalWords:  accessors DSLs gensym gensyms

## Local variables:
## mode: org
## End: