[Haskell-cafe] Re: about Haskell code written to be "too smart"

Colin Adams wrote:

2009/3/27 Achim Schneider :

...

wren ng thornton 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[1] as well as developer[2] 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[1]. [1] In the sense of using the code, either as app or library [2] In the sense of editing/reading the code. Understanding [2] usually involves understanding [1]. [3] 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.