[Haskell-cafe] Literate Haskell
Jesper Louis Andersen
jlouis at mongers.org
Tue Feb 22 04:32:43 EST 2005
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!
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.
More information about the Haskell-Cafe