[Haskell-cafe] Literate Haskell

[Jesper Louis Andersen]

Quoting Jérémy Bobbio (jeremy.bobbio at etu.upmc.fr):
> I really see Literate Haskell and Haddock as two orthogonal tools, and 
> that help me to focus when writing docs.

It impresses me SO much that the COMPUTER SCIENTIST have found a WAY to
ELEVATE mere tools likke Haddock and Literate Haskell as elements in a 
VECTOR SPACE. Furthermore it seems that the SAME vector space has LANGUAGES
as well, and moreso; It is an INNER PRODUCT SPACE, since one can talk about
ORTHOGONALITY. One could have used the term ''Lineraly independent set'',
but NO! One should use the magical, term Orthogonal! Heed my words! 
Orthogonal!

Fun aside, I think you are right, but I disagree literate haskell is the
way to write the ``how does this fit together'' question. Having just 
completed a quite big program written all in literate style, I can actually
put up some comments about it:

* It is hard. There is a thin line between having meaningful information
  in the comments and nothing but redundancy, compared to the source code.

* There is many changes. All the time you change code semantics and then
  you have to read the comments around and check them for correctness.

* There is an abstraction gap. Your thoughts can separately be given at
  a very high level. If interspersed with code, you are explaining at a
  much lower (and precise) level what your program is actually doing.

I have a program of 2500 Lines. It is, typeset in LaTeX, 155 pages of report
and literate documentation. That is awfully much for 2500 Lines of source code.
Currently my feeling is that the added effort of writing it literate style 
does not add to the general understanding of the source code. This is partly
because the source code is imperative at many points (it is ML - who said you
can't just push in a couple of ref cells?). And also because the code in
question is quite complex (due to the destructive updates, actually). I think
you want 3 things:

* API documentation (Haddock fills this gap). It is the for the programmer who
  wants to see how a given function should be called and be given the abstract
  view of it's semantics as a black box.

  Furthermore, Haddock provides a very succintly different but important view
  of my Modules: The ``SML signature'' view to type annotations, where type
  annotations are all presented in the same location for overview and is
  disconnected from the actual implementation. Together with proper
  documentation, this gives a very good overview over programs.

* Documentation of the ``hard semantical parts''. The meaning of some functions
  needs elaboration since they are either hard to understand or they have some
  subtle point you commonly overlook. 

* Documentation of the high-level structure. 

My view is that Haddock, code comments and LaTeX fits these 3 quite well. On
the other hand, if writing code by example to teach others about it, sending
email with code etc, I like to have literate haskell style. But I do not tend
to use it for large projects.  

-- 
jlouis