[Haskell-cafe] Re: about Haskell code written to be "too smart"
barsoap at web.de
Fri Mar 27 09:09:39 EDT 2009
Colin Adams <colinpauladams at googlemail.com> wrote:
> 2009/3/27 Achim Schneider <barsoap at web.de>:
> > wren ng thornton <wren at freegeek.org> wrote:
> >> Colin Adams wrote:
> >> > A reference to a research paper is fine to show where the ideas
> >> > came from, but that is not where the library documentation
> >> > should be.
> >> Yeah, that's bad. 'Documentation' like that should be corrected
> >> with Extreme Prejudice.
> I think I agree with that (I say I think, as I'm not sure what Extreme
> Prejuidice means).
Shoot err... rewrite before asking. If in doubt, annihilate.
Considering all options, just do it. Pity is a thing for judges, not
hackers. Something along those lines.
> > The main problem with research papers as documentation is the papers
> > usually being outdated wrt. the current library version: Literate
> > Haskell is utterly underused.
> That's surely a problem, and a significant one.
> But what irks me is the time taken to find one small piece of
> information (how to use a single function).
> I would guess on average about the time to read 1/3 of the paper
> (since the back matter needn't be examined).
Hm. Yes. OTOH, I very much appreciate background information, it
usually contains very insightful information about the overall idea and
behaviour of a library. I'm by no means a domain expert for any
and every library I want to use.
In school, we were required to write both user as well as
developer documentation alongside to commenting our code. I tended
to loathe it, but it's very, very sensible in retrospect.
There was some discussion a while back here on the cafe about enabling
users to write additional documentation into a wikised hackage;
together with an #haskell-doc-tutor irc channel, we could have an
excellent solution to both lacking documentation as well as newbies
not being sure were to start and/or intimidated by pointless usage of
(.). Additionally, you get the chance of earning credits and naming and
shaming Haskell's godfathers.
 In the sense of using the code, either as app or library
 In the sense of editing/reading the code. Understanding  usually
involves understanding .
 Judging from his code, I guess dons' apartment looks just like
mine: Lots of left-over bits lying around that you tend to stumble
over and are unsure about why they are still there. I swear, someday
I'm going to use those two 5 1/4" floppy drives...
(c) this sig last receiving data processing entity. Inspect headers
for copyright history. All rights reserved. Copying, hiring, renting,
performance and/or quoting of this signature prohibited.
More information about the Haskell-Cafe