Unit interfaces
---------------

[ NOTE: This is old. I went to something similar to alt. 3, with main.slul ]

Alt.1: mixed interface/impl  (Java style)
Alt.2: header + impl         (C style)
Alt.3: global header + impls (C internal.h + *.c)
Alt.4: interface then impl   (Turbo Pascal / Delphi style)

Strict improvements to the above:
Alt.1:
- Some keyword that stands out? (perhaps upper case)
  We need three levels: private, module-internal, exported
  (downside: first keyword on line is no longer guaranteed to start with func/type/data)
Alt.2:
- Sections for files


Usability/Safety:
- we want exported methods/types/variables to stand out   [   A2 A3 A4]
- also nice if they are easilly searchable                [   A2 A3   ]
- it should be clear which file an intf. decl. belongs to [A1 A2 A3 A4]
- avoid jumping around between files                      [A1    A3 A4]
- avoid jumping around within files                       [A1 A2      ]
- avoid merging of files                                  [A1 A2    A4]
- avoiding large directory listings                       [A1    A3 A4]

Incremental compilation:
- Full re-compilation avoidance with file timestamps only [   A2      ]
- Re-compilation avoidance by scanning headers            [   A2 A3 A4]

Fast compilation:
- Single pass compilation possible                        [   A2 A3   ]
  *If* we allow sizeof expressions in enums and arrays, then that will
  need special handling.
  With A4 (Interface then impl), it is possible but requires jumping
  between files.


How to avoid repeating yourself in A2/A3/A4:
- Have documentation only in one place?
     - interface is most common
     - but also risks getting out of date
     - for internal interfaces, there is perhaps not much of a benefit of
       having documentation in one place.
- Have a one line summary in the interface, and detailed documentation in
  the impl?
     - but usually the name/parameters/fields should tell what the function/type does