[Swan] a discipline for declarations in C

[D. Hugh Redelmeier]

In the C code, names should have the smallest scope reasonable.  This
makes the code more understandable for humans and compilers.

- define variables local to a function in the smallest block that makes sense

- make each function and non-local variable file-static if possible (i.e.
  if it is only used within one source file)

- each shared function and variable should be declared in a header
  exactly once (with the storage class "extern").

- each shared function and variable should be defined exactly once, in a
  .c file (without the storage class "extern").

- Of course there should be a simple relationship between the header
  that declares the name and the .c file that defines it.  If possible
  the basenames of the two files should be identical.

- the .c file defining the shared function or variable should #include
  the header file declaring it.  This way the compiler can check that
  the declaration and definition match.

- All function and variable declarations in a header file should
  explicitly include the keyword "extern".  This makes it clear that
  they are intended as declarations, not definitions.

- The storage class keyword "extern" should almost never appear in a
  .c file.  This makes it clear that these are definitions, not just
  declarations.

This convention was followed when I maintained Pluto.  There has been
some bitrot that needs to be fixed.  In fact a lot of the
modularization has decayed.