Hello! I'm curious what experienced Haskellers think about using literate Haskell in daily work. It seems to me like a good idea, since during coding it often helps to write down one's thoughts (often, I find a solution to a complicated problem in this way). What are your experiences with using literate Haskell? TIA Dmitri Pissarenko -- Dmitri Pissarenko Software Engineer http://dapissarenko.com
On Fri, 18 Feb 2005, Dmitri Pissarenko wrote:
I'm curious what experienced Haskellers think about using literate Haskell in daily work.
It seems to me like a good idea, since during coding it often helps to write down one's thoughts (often, I find a solution to a complicated problem in this way).
What are your experiences with using literate Haskell?
I used to use it - I also like to note things in among the code. Now I tend to use Haddock documentation more. -- Mark
On Saturday 19 February 2005 01:38, Mark Carroll wrote:
On Fri, 18 Feb 2005, Dmitri Pissarenko wrote:
It seems to me like a good idea, since during coding it often helps to write down one's thoughts (often, I find a solution to a complicated problem in this way).
What are your experiences with using literate Haskell?
I used to use it - I also like to note things in among the code. Now I tend to use Haddock documentation more.
From my point of view, there is two different questions that some documentation might answer: "How does this work?" This documentation should describe the implementation design, issues, tricks, etc. I think that Literate Haskell is well suited to write documentation answering this question. By printing and reading a whole module, it is easy to follow the implementor thoughts. "How should I use this?" This documentation should describe how to use a module (let's say "its API") without understanding more than needed how it works under the hood. It should be indexed and hyperlinked when one needs to quickly lookup the behaviour for some function. Haddock was designed to write this kind of documentation. I really see Literate Haskell and Haddock as two orthogonal tools, and that help me to focus when writing docs. Cheers, Jérémy.
Quoting Jérémy Bobbio (jeremy.bobbio@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
On Fri, Feb 18, 2005 at 09:21:00PM +0100, Dmitri Pissarenko wrote:
I'm curious what experienced Haskellers think about using literate Haskell in daily work.
This isn't a deep answer, but I find both of Haskell's literate syntaxes more trouble than they're worth. The leading "> " syntax makes a lot of editor operations (joining lines, changing indentation) more cumbersome, and it takes away two characters that every-so-often come in handy at the end of a line. The LaTeX syntax is too verbose unless you're really writing LaTeX (so I'm sure for papers it's great). I do use a literate style sometimes, but I just use ordinary comments for it. As far as I'm concerned, the psychology of having comments be the default mode is not worth the minor annoyance it causes me. I use vim, which can handle free-form text with a comment leader very well, but probably isn't flexible enough to make writing code with a leader as comfortable as without. Andrew
Dmitri Pissarenko writes:
I'm curious what experienced Haskellers think about using literate Haskell in daily work.
My experience is that literate-style documentation tends to be out-of-sync or misleading as quickly as any other kind of documentation. It doesn't matter that much whether you write | This function does something. | | > the_function ... or whether you write (for Haddock): | -- |This function does something. | | the_function ... It's just a difference in syntax. I've also found that many of the projects I have seen actually written in literate-style did *not* come with a particularly good documentation. (Darcs probably is the exception; because it is documented very well.) I use literate Haskell mostly when writing articles that include code. For that, it is great. But for everyday programming, I prefer Haddock. Peter
Thanks all for your answers! -- Dmitri Pissarenko Software Engineer http://dapissarenko.com
participants (6)
-
Andrew Pimlott -
Dmitri Pissarenko -
Jesper Louis Andersen -
Jérémy Bobbio -
Mark Carroll -
Peter Simons