>> unzip = foldr (\(a,b) ~(as,bs) -> (a:as,b:bs)) ([],[])
>> Not exactly intuitive. Could be better. I'm assuming that George's point
>> is that this documentation leaves plenty of room for expansion.
> OK, you fire up Hugs and type :t unzip and Hugs tells you that
> unzip :: [(a,b)] -> ([a],[b])
> Completely clear, unzip takes a list of pairs and returns a pair of lists.
As a new user (and a complete newbie to FP), perhaps I can shed some light
on something here....
- The above "explanation" is worthless.
- It is completely and absolutely worthless.
- Indeed "explanations" like this cause more harm than good.
- In that they have no good qualities at all, but can cause harm.
What old-timers (and the occasional wunderkind) often forget is that
regular newcomers -- especially newcomers to a completely different
approach to programming -- are flooded with a whole bunch of new concepts.
First you have to understand the paradigm, something involving unlearning a
lot of what you already know. Then you have to learn the syntax, something
non-trivial in an expressive language full of syntactic sugar. Then you
have to learn the standard library. The order may vary, of course.
It takes time to digest and understand these concepts. And even after
you're at the stage of being able to puzzle out stuff that looks like
executable line noise -- "unzip = foldr (\(a,b) ~(as,bs) -> (a:as,b:bs))
([],[])" indeed! -- you're still unsteady on your metaphorical legs. You
may have decoded the line noise correctly. You may not have. You're too
much of a neophyte to know for certain. Uncertainty is not a good thing
while learning. It leads to annoyance and frustration.
Terse "explanations" like the one taken from the docs only muddy the
waters. They don't help. Smart-ass comments from old-timers help things
even less. Instead you get annoyance, frustration and eventually you lose
a potential practitioner. This does nobody any good.
Good docs, on the other hand, are very helpful. Even if it strikes an
old-timer as redundant to explain "unzip = foldr (\(a,b) ~(as,bs) ->
(a:as,b:bs)) ([],[])" as "this function takes a list of pairs and returns a
pair of lists", believe it or not this actually helps newbies. At the very
least it affirms that the newbie's decoding of the line noise "unzip =
foldr (\(a,b) ~(as,bs) -> (a:as,b:bs)) ([],[])" is correct. This reduces
uncertainty in the newbie's mind and increases confidence. Increased
confidence means increased interest. Increased interest means increased
study. Increased study means potentially a new practitioner of the
language (and paradigm). This is ultimately good for everyone.
On the flip side, if the user's decoding of the line noise "unzip = foldr
(\(a,b) ~(as,bs) -> (a:as,b:bs)) ([],[])" is incorrect, the documentation
will flag this as an error. The user gets immediate feedback on the
matter. A quick check of some syntax items (maybe the user forgot to take
'~' into account) leads to comprehension. This reduces uncertainty in the
newbie's mind and increases confidence. Increased confidence means
increased interest. Increased interest means increased study. Increased
study means potentially a new practitioner of the language (and paradigm).
This is ultimately good for everyone.
Of course another benefit of well-documented standard libraries is that it
spares us (partially) from the blight of wheel reinvention. If I'm writing
a non-trivial program in Haskell, a well-documented standard library means
I can quickly find the existing functions that do what I want. I don't
have to puzzle over line noise like "unzip = foldr (\(a,b) ~(as,bs) ->
(a:as,b:bs)) ([],[])" to see if unzip does something I plan to implement
myself (possibly in a fashion superior to what I originally conceived). A
well-documented standard library also documents something else: it
documents Best Current Practices in the form of idioms and programming
patterns for the language. Reasonable documentation implies the idioms.
Good documentation highlights the idioms. Bad documentation (and smart-ass
old-timer comments) actively conceal the idioms.
Now before I get challenged as to whether or not I'll put my time and
effort where my mouth is, the answer is a qualified maybe. Currently I'm
only learning functional programming. My documentation efforts would most
likely be worthless. As I grow into the paradigm (and language), if I
choose to continue with Haskell as my functional language of choice, I will
most certainly want to contribute to the community of practitioners. This
contribution may well be in the form of beefed up documentation if this is
what I'd be best for.
--
Michael T. Richter <[EMAIL PROTECTED]> http://www.igs.net/~mtr/
PGP Key: http://www.igs.net/~mtr/pgp-key.html
PGP Fingerprint: 40D1 33E0 F70B 6BB5 8353 4669 B4CC DD09 04ED 4FE8
