Hi Ivan, there is a committee? Günther Am 27.10.10 12:37, schrieb Ivan Lazar Miljenovic:

2010/10/27 Günther Schmidt:

...

Hi all,

this may be an odd question to some, but I think it's actually quite an un-extraordinary one.

Who's in charge?

Of Haskell I mean. If there was some alien from Planet Java to land on Planet Haskell and demand to be taken to our leader, whom would we take him to? The Haskell' committee?

2010/10/27 Ivan Lazar Miljenovic :

2010/10/27 Günther Schmidt :

...

Hi all,

this may be an odd question to some, but I think it's actually quite an un-extraordinary one.

       Who's in charge?

Of Haskell I mean. If there was some alien from Planet Java to land on Planet Haskell and demand to be taken to our leader, whom would we take him to?

The Haskell' committee?

They're just figureheads for a shadowy cabal :-D -- Dougal Stanton dougal@dougalstanton.net // http://www.dougalstanton.net

there still isn't even a mail client library, I wonder whom to escalate this to, and who is going to do something about it?

So, if it is libraries you care about, then it is pretty-much a free- for-all open source world. People implement libraries that matter to themselves, scratching a itch, and if we are lucky, they release them to the world at large. There is no steer or guidance from any leader. We are all volunteers here. Indeed, I don't think any one "leader" could possibly anticipate everyone's library needs and magically arrange for someone to finish the work two weeks before you even ask for the library. Of course, posting a request for some specific library on a mailing list might just prompt someone who shares the same itch as you to go away and implement it. Or you might find collaborators who are willing to help you to design and implement it. That counts as escalation, and getting the job done, even if you would prefer just to grab something off the shelf for free. Regards, Malcolm

I think you can commission Well-Typed or other members of Industrial Haskell Group to build such things. However it might not be very cost effective if you aren't yourself selling software that works atop of it. If a library is more than a one-person effort, the so-called "strike forces" seem to have been successful recently.

I am Spartacus ------------------ -----Original Message----- From: Günther Schmidt Sender: haskell-cafe-bounces@haskell.org Date: Wed, 27 Oct 2010 17:08:28 To: Malcolm Wallace Cc: Subject: Re: [Haskell-cafe] who's in charge? Dear Malcolm, since there is no mail client library even after 10+ years I suggest to rethink the approach, because frankly, it's not working. Günther _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Quoth =?ISO-8859-1?Q?G=FCnther_Schmidt?= ,

since there is no mail client library even after 10+ years I suggest to rethink the approach, because frankly, it's not working.

Or on the contrary, it may illustrate the advantage of this system. 10 years ago, the putative Haskell Institute might have determined there was surely a need for a mail client library, and anyone could see how it ought to work. But the absence of any such package after all this time casts some doubt on that, doesn't it? I personally don't think it's a great idea. I'm using a Haskell mail client to correspond with you right now. If I were to start from scratch today, and there were a mail client library, I'm sure I would find something useful in there, but I'm not sure it would all adapt without changes to my application. Depending on what you actually need, I think you should look at the HaskellNet package (IMAP etc.), SMTP, mime-mail. See what they do, and how they work. I don't know, I really haven't looked at them myself so I don't know what you're in for - it might work like a dream. Or it may be that their APIs don't really suit your needs - the way they handle strings, character sets, I/O, etc. For me, that kind of issue looms very large in this area of computing, and that's why I'm skeptical of big packages that try to tie it all up. The author of this package will spend a lot of time, trying to serve the needs of a dozen active users with very disparate needs. Donn Cave, donn@avvanta.com

Dear John, Am 28.10.10 23:57, schrieb John Goerzen:

On 10/27/2010 10:08 AM, Günther Schmidt wrote:

...

Dear Malcolm,

since there is no mail client library even after 10+ years I suggest to rethink the approach, because frankly, it's not working.

Why do you keep suggesting this?

http://hackage.haskell.org/package/WashNGo

Thanks for this, I wasn't aware that it also offered email handling.

There is no need for a mail client library on many platforms. Just pipe the data to /usr/sbin/sendmail and poof. Done.

That would work well for sending (on Unix), but not for receiving.

Has it occurred to you that there is no mail client library because there is no need for one?

No, to be honest, it never has. I absolutely cannot conceive of it. It'd be like not having HDBC for instance and having to roll my own database driver. It wouldn't have mattered how great a language haskell is, had it not had HDBC I would have had no choice but to drop it and move on. Database connectivity to me is one of the essential things I need to be able to do, and so is email, as is xml, as is http.

Frankly I am unimpressed with monster 10,000-SLOC mail client libraries that make it a lot harder for me to pipe some stuff to sendmail.

Well it's not necessarily only about sending mail, it's more about the whole shebang one wants / needs to do with mail. Günther

Dear John, Am 29.10.10 01:23, schrieb John Goerzen:

On 10/28/2010 05:44 PM, Günther Schmidt wrote:

...

...

There is no need for a mail client library on many platforms. Just pipe the data to /usr/sbin/sendmail and poof. Done.

That would work well for sending (on Unix), but not for receiving.

Quite true. For receiving, we have tools like fetchmail, imapsync, offlineimap, MH, the list goes on.

The Unix philosophy is all about pluggable bits and pieces that can be reused all over the place. I like that philosophy. It means that one doesn't have to reinvent mail handling n times for n languages. As long as your language can do some piping, you can handle the basics of mail.

Now, I'll grant you that fetchmail won't solve every possible mail access scenario. It isn't, for instance, good enough to be the backend of OfflineIMAP. But I do want to push back on the notion that, on POSIX platforms, these things have to be reinvented for each language. It just isn't so.

...

...

Has it occurred to you that there is no mail client library because there is no need for one?

No, to be honest, it never has. I absolutely cannot conceive of it. It'd be like not having HDBC for instance and having to roll my own database driver. It wouldn't have mattered how great a language haskell is, had

Hmm, I am perhaps uniquely qualified to say "been there, done that" ;-)

The existing Haskell database drivers at the time didn't meet my needs. They lacked some things I considered rudimentary and standard. I felt about them approximately the way you did about mail.

I decided that Haskell would be enough of a long-term win to justify writing HDBC. So I did, and I'm glad of it.

I think you are getting some resistance here because you appear to be demanding that others volunteer their time to meet your pet need.

Well this is exactly what I have the most problem with. This assumption. It is exactly this where I am seriously taking offense. I suddenly am taking fire from all sides for things that were actually said more bluntly by people before me. One of the responses out of the hysteria that developed even suggested I was calling for a dictator. Get a grip. Other people before me lamented about the lack of a good email client library as can be seen here: http://www.reddit.com/r/haskell_proposals/top/?t=year Do not assume that the words that were put into my mouth by hysterical posters are indeed my own, they are not. Consider what I did say and not what others suggest I did. I also noticed that one of your co-authors made statements regarding the quality of available libraries on hackage, without being blown to bits. My own posts in this thread did not come close to even suggesting that.

This attitude doesn't usually work.

Nor should it.

...

it not had HDBC I would have had no choice but to drop it and move on.

Or you could have written HDBC. Or you could have used unixODBC, which already solved that problem. (Whoops, did I do a tiny bit of wheel reinvention myself? Indeed I did, with the PostgreSQL HDBC backend. There are reasons for it though.)

...

Database connectivity to me is one of the essential things I need to be able to do, and so is email, as is xml, as is http.

HTTP is another thing that can easily be "outsourced". I've been somewhat unhappy at various points in time with the Haskell HTTP libraries. No problem, though; there's always Curl. One can choose the Haskell libcurl binding or call the Curl binary directly; it's even portable to all sorts of platforms, and you get not just HTTP, but FTP, Gopher, SCP, and some other useful protocols along for the ride.

...

Well it's not necessarily only about sending mail, it's more about the whole shebang one wants / needs to do with mail.

So if it's not about sending, it's about receiving or accessing stored mail.

The Maildir spec is very simple and easily implemented. Google tells me there is an implementation in xmonad already. Tools to get mail into Maildirs are plentiful and featureful.

I appreciate that you are a proficient Unix / Posixler but it just so happens that I was thinking more about accessing POP3 account, which I imagine to a fairly common usage scenario. To my defense I did mention that the lack of certain libraries does not cause the same problem to more capable people, such as yourself, as they do to people less capable. Hey you rolled your own database access library (and shared it, much appreciated). But most would struggle with such a lack. There is this one posters who likes to repeatedly point out how none of his programs ever needed email, so how could it be a problem then. Well good for him, but in my experience it's needed.

My point is this: using existing tools on your system, and turning a blind eye to their implementation language, can be a perfectly workable, and even elegant, solution.

Example: say you needed to copy a directory containing files and directories. Is that easy to do? You could probably whip up some sort of recursive file copying thing to do that in a few lines of code. But will it handle things like preserving permissions bits, ownership, ACLs, symbolic links, not following symlinks, etc. correctly? We already have a tool that does all those things (cp -a), so using it is, in my book, more elegant than writing a (probably more buggy and certainly less tested) clone.

So I'm pushing back on your unstated premise; namely, that a Haskell library for mail handling is necessary for efficient mail handling in Haskell. I don't think it is.

duly noted :)

-- John

On 10/28/2010 07:48 PM, Daniel Peebles wrote:

Would anyone be interested in a project for a full-featured mail library? I don't think I'm capable of writing the whole thing myself, but I've started a github project at URL and would be happy to collaborate in IRC channel #channel on freenode.

Would have resulted in a very different response.

That is absolutely well put. Günther, I don't condone hostility on the part of anyone on this list, obviously. If you experienced it, it's not right. By the same token, you came in here talking about "escalating" a problem, and saying that an entire process was fundamentally broken because you hadn't found a solution to your particular problem. What people are trying to tell you is: 1) That argument isn't well-formed, because that conclusion doesn't follow from the premise. In other words, your pet problem may not indicate a bad community/process. 2) This is a "doocracy" (man do I hate that word!). If there is a problem, here's what you should do about it, in descending order of attractiveness: a) Fix it yourself b) Pay someone else to fix it c) Motivate or politely encourage others to fix it, providing moral support, etc. The key point is: you haven't paid any of us for this, and you have nothing even close to some sort of support contract. I perceive a sense of entitlement on your part that people owe you no-cost coding. That's just not how the community works. Whether or not you really have that sense, I don't know, but your messages convey it nonetheless. 3) There are several existing solutions for doing mail in Haskell, and those of us that have used them have, to date, found them perfectly adequate. a) Some of them Google or hackage searches could have informed you of. You should do more research before insulting an entire community. b) It is, of course, possible that these solutions don't meet your needs. In that event, see #2. On a personal note, some of you with moderately long and extremely sharp memories, or perhaps access to Google, may find some messages from me in my early Haskell days grousing about this or that problem. Ultimately, the questions for me were: 1) Is the problem real? In other words, was there simply something I didn't know/understand about the language that would have made it go away? 2) Can I fix it? If so, I should try. 3) How annoying is it? I wrote some of my libraries when I was still a Haskell newbie (and with the number of Ph. D's around here, I'm not always sure I've shed that title yet!)... sometimes that shows in the older code that's out there. But that's OK; it solved my problem and, truly, I had fun writing them. Sometimes it is easier to write a Haskell library to solve the problem than to use an off-the-shelf library in $LANGUAGE. -- John

2) This is a "doocracy" (man do I hate that word!).  If there is a problem, here's what you should do about it, in descending order of attractiveness:

a) Fix it yourself

b) Pay someone else to fix it

c) Motivate or politely encourage others to fix it, providing moral support, etc.

The key point is: you haven't paid any of us for this, and you have nothing even close to some sort of support contract.  I perceive a sense of entitlement on your part that people owe you no-cost coding.  That's just not how the community works.  Whether or not you really have that sense, I don't know, but your messages convey it nonetheless.

I understand why this and have accepted it. That being said the lack of certain well documented high quality and widely written about libraries are probably the biggest challenge to Haskell adoption after the IO Monad. As a beginner I really have struggled to understand what the right libraries to use are for common problems (specifically databases). However other problems like the lack of a high resolution, well documented date time library were also a source of friction. The reason I am using haskell is to solve specific types of difficult problems in machine learning and it is very good at that. Gluing a fully working stack together has been challenging. I agree that people need to be proactive about solving their own problems but whenever I here any open source community (yeah...everyone not just haskell) tell beginners to contribute a package I always scratch my head with a little bit of wonder. Would you really want a package that someone like me who is still trying to figure out how to utilize haskell's features would build? Do you want my outrageous non-use of the Monads that haskell offers? Haskell adoption is a frequently discussed topic and I personally believe that haskell will and should remain a niche language for solving certain types of problems. However if others in the community take the position that success is determined by adoption then Haskell needs to have a solid and well documented story about all the problems that developers that write regular applications face including database communication, ORMs, XML, Web Services, web pages (I know there is Yesod just making the point),model view controllers (hits self in head), etc... If "regular" developers are the target then they want to be told what to do and what to use (with something like MSDN or some of the big java toolkits), not discover it for themselves. I say this with superior confidence after spending 2 years in a large (2000+) developer organization. I believe as a relative newcomer that haskell is best utilized when solving complex and difficult to reason about problems that involve small teams of highly skilled developers. Most software does not meet this criteria. There are a wide variety of inferior technologies ;-) (ahem java) that can be used to build most applications in the world. Haskell should not try to compete because it can't (marketing problem), and there are many things that it enables to be done better. Not intending to flame (or otherwise ignite the fires of passion) at all. Steve

On Fri, Oct 29, 2010 at 8:31 AM, Ben Millwood wrote:

Besides, I'd think that often what Haskell developers lack is time more than skill - there are plenty of tasks that could be done without advanced knowledge of deep abstractions, if only someone could put aside a few weekends for them. For example, writing low-level FFI bindings is almost mechanical (i.e. requires basically no actual ingenuity) with the right tools, but it takes time and effort, so libraries go unbound.

It's more than just that; when talking about libraries for some specific task, what matters most is actually the language-agnostic knowledge of the task itself. Particularly in the case of IO-oriented libraries with lots of FFI bindings, someone who knows the underlying C library (or what-have-you) inside and out is probably going to get the best results from writing a library, even with little knowledge of Haskell. - C.

It's working just fine. I've never wanted a mail client library. :) -- Lennart 2010/10/27 Günther Schmidt :

Dear Malcolm,

since there is no mail client library even after 10+ years I suggest to rethink the approach, because frankly, it's not working.

Günther _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

On Oct 27, 2010, at 10:08 AM, Günther Schmidt wrote:

Dear Malcolm,

since there is no mail client library even after 10+ years I suggest to rethink the approach, because frankly, it's not working.

Hello! I am in charge, sorry for the delay! A number of years ago I tried to form a MIME strike force to create a library that would be suitable for composing mail messages, decoding mail messages, or transforming mail messages. But received no real interest: http://www.mail-archive.com/haskell-cafe@haskell.org/msg21872.html The fact that it is now considered an oddity (by some) that there is no standard, well support mail library is a sign of great progress in my opinion. The driving force is likely to be web development platforms such as happstack, snap, and yesod, because one often wants to integrate email with a web site. (such as send emails to members, etc). That said, there have been many attempts at various portions of the mail infrastructure over the years. As part of that strike force attempt I create this mime library (not on hackage): http://src.seereason.com/haskell-mime/ It can parse and decode multipart messages. And it has the beginning of an interface for composing messages. One thing I attempted to do was create a mail composition DSL that only allowed you to construct valid messages. For example, some headers can only appear once, and others can appear multiple times. So I attempted to encode that into the DSL. I was successful to some degree. There is also the mime-string library on hackage which does MIME parsing. There is the new mime-mail library for creating and sending MIME messages. happstack had the beginnings of a MTA at one point in time, but was removed until someone comes along with the desire and time to really implement it. There is the Postmaster ESMTP server, http://gitorious.org/postmaster which acts as a MDA for receiving mail and filtering it into folders. It allows you to write your filtering rules in Haskell instead of some obtuse filter language (e.g., procmail). And there are other projects I have not mentioned as well. I guess part of the question is, do you specifically mean a 'mail client'. There are a lot of pieces to the mail puzzle including, MUA, MTA, MDA, MIME, etc. And there is the reading of saved mail formats like mbox, Maildir, etc. And then there are the various protocols like SMTP, POP3, IMAP4, etc. And things like GPG signatures and encryption. Using the libraries that are available right now I can create a mime email and send it via sendmail or via an SMTP smart host. I can also use a well established program like dovecot to receive mail and then decode messages using mime-string on haskell-mime. That gets me pretty far for what I need to do. Writing a competitor to mutt or gmail would be more difficult due to some missing pieces. But, then again, I think most people are satisfied enough with mutt and gmail, so not many people have any motivation to replace them. Same thing with a competitor to qmail/ dovecot/etc. Those tools are in place and work pretty well. So, replacing any of those really only becomes interesting if you are going to do something really new -- not just implementing them in your favorite language. Anyway, I do think there will be growth in the haskell mail library domain. Specifically the stuff that would be useful for integration with web applications. - jeremy

On Wed, Oct 27, 2010 at 5:28 PM, Gregory Collins wrote:

Günther Schmidt writes:

...

Hi Malcolm,

well if I would like to point out that, for instance, Haskell exists for a lot more than 10 years now, and that, while the language per se rocks, and there are cool tools (cabal) and libraries (list, Set, Map), there still isn't even a mail client library, I wonder whom to escalate this to, and who is going to do something about it.

You're too busy?

+1 Gunther, I've pointed out three libraries that deal with email (mime-mail, SMTPClient, HaskellNet). What is the precise functionality that you're looking for that is missing? This crusade of "I want to speak to the supervisor" is juvenile and close to trolling. Michael

On Wednesday 27 October 2010 17:38:37, Günther Schmidt wrote:

As we are 10+ years now still without one of the most essential libraries any programming language needs

Hmm, I suppose that the absence of such a library may indicate it's in fact not essential at all. If there were a widespread need, there'd already be one or more around.

2010/10/27 Daniel Peebles

As we are 10+ years now still without one of the most essential libraries

...

any programming language needs I guess it's not that easy.

I don't even know how to respond to that.

Don't feed the trolls?

Hi Greg, Am 27.10.10 17:56, schrieb Gregory Collins:

Günther Schmidt writes:

...

Hi Greg,

busy no, merely incompetent. If I was capable of writing a good library I wouldn't have bothered, I'd just rolled it myself and published it. I am capable, giving sufficient time, to write code that will get my email for me. But it's gonna be bad, hackish and ugly.

As we are 10+ years now still without one of the most essential libraries any programming language needs I guess it's not that easy. It has just been recently that I wanted to do email via haskell. I was very surprised not find one in place already. As Michael pointed out, there are a couple of basic packages, of varying levels of completeness. Part of the reason there isn't a "complete" solution on par with that of Python's is that sending& receiving email isn't actually as easy as it looks.

No argument there :)

You'd have to deal with several protocols (SMTP, POP, IMAP at a minimum, each with SSL variants and half a dozen authentication schemes), dozens and dozens of RFC standards (see the full list at http://www.imc.org/rfcs.html and allow your mind to boggle), plus all of the weird exceptions and workarounds you need to add in to deal with all of the broken software that's been in use over the years.

Python has excellent email support *now*, but it wasn't always so, and the reason things have improved is that there are a whole lot of engineers employed *in industry* who have been paid to work on these things for years until they got it right. Guido works for Google, you know. I'm not sure how many people are being paid to write Haskell code right now (not including graduate students), but I'd wager the number is less than 200 *worldwide*.

Basically that is my question: If there is someone at the top who has an eye on this. That essential libraries come about. I am aware that Haskell is a project without industry backing so some things will have to happen a lot slower. I'm just wondering if there is someone who steers Haskell in that direction.

There are areas in which we simply can't compete right now and this happens to be one of them.

G Günther

Günther Schmidt writes:

Basically that is my question: If there is someone at the top who has an eye on this.

There isn't. (Just like there isn't one in most situations, it's all complex networks of interactions and nobody really in control. Get used to it.)

That essential libraries come about.

What does "essential" mean? Something a hypothetical dictator wants, but nobody else? For surely, if your email library was so essential, it'd be included among the hundreds of libraries on Hackage? Perhaps it is a lot less important than you think? (None of my programs need to send email, so it's certainly not essential to me.) Or perhaps sufficient functionality is in the libraries suggested by Michael, and you just didn't find it when you looked?

I am aware that Haskell is a project without industry backing

This isn't exactly true, GHC is developed with support from Microsoft.

so some things will have to happen a lot slower.

This isn't exactly true either, productivity seems only weakly correlated to funding - at least, it is my experience that many of the most productive people are programming as a hobby.

I'm just wondering if there is someone who steers Haskell in that direction.

No. -k -- If I haven't seen further, it is by standing in the footprints of giants

On 28/10/2010, at 4:38 AM, Günther Schmidt wrote:

As we are 10+ years now still without one of the most essential libraries any programming language needs I guess it's not that easy. It has just been recently that I wanted to do email via haskell. I was very surprised not find one in place already.

There is no standard E-mail library for Ada, Fortran, COBOL, PL/I, or a great many languages. Fortran and COBOL have been around for fifty years, not ten.

2010/10/27 Günther Schmidt

Hi Malcolm,

well if I would like to point out that, for instance, Haskell exists for a lot more than 10 years now, and that, while the language per se rocks, and there are cool tools (cabal) and libraries (list, Set, Map), there still isn't even a mail client library, I wonder whom to escalate this to, and who is going to do something about it.

Maybe this should be on an FAQ. Q: Whom do escalate this to? A: http://www.reddit.com/r/haskell_proposals/ Q: Who is going to do something about it? A: You and other volunteers. Happy Hacking! Jason

I understand your frustration at not having free tested libs ready-to-go, Java/any-other-mainstream-language programmers tend to expect this and usually get it. If a lack of libs is a dealbreaker for you and you want to use a functional programming language with some of Haskell's advantages (like immutability, lazy data structures and STM) I encourage you to check out Clojure [1] a nicely designed Lisp. It is tightly integrated in to the JVM and you have access to all the Java libs you want. -deech [1] http://clojure.org/ 2010/10/27 Günther Schmidt

Hi Malcolm,

well if I would like to point out that, for instance, Haskell exists for a lot more than 10 years now, and that, while the language per se rocks, and there are cool tools (cabal) and libraries (list, Set, Map), there still isn't even a mail client library, I wonder whom to escalate this to, and who is going to do something about it.

I understand some parties wish to avoid success at all costs, while others, commercial users, benefit from the edge haskell gives them already and which probably can help themselves in case of, again, for instance a missing mail client library.

And then there is the ones like me, which also want to benefit from the edge Haskell gives them over users of other languages and want to develop Real World Apps and who cannot easily help themselves in case of a missing mail client library.

So while there are many aspects of the future of haskell, who effectively is it that steers the boat?

Günther

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Also, this is a complete aside but what the heck. :-) Has anyone else been driven crazy by the way that Java code and libraries are documented? It seems like whenever I try to figure out how to use a piece of Java code, the functionality is spread out over a huge collection of classes and methods so that it is impossible to figure out where things actually happen and how the code is supposed to be used. Am I correct to perceive this as a general trend in Java, or is it just the projects that I looked at and/or my lack of experience in how Java sources and libraries are organize? Cheers, Greg On 10/28/10 9:53 PM, aditya siram wrote:

I understand your frustration at not having free tested libs ready-to-go, Java/any-other-mainstream-language programmers tend to expect this and usually get it.

If a lack of libs is a dealbreaker for you and you want to use a functional programming language with some of Haskell's advantages (like immutability, lazy data structures and STM) I encourage you to check out Clojure [1] a nicely designed Lisp. It is tightly integrated in to the JVM and you have access to all the Java libs you want.

-deech

[1] http://clojure.org/

2010/10/27 Günther Schmidt mailto:gue.schmidt@web.de>

Hi Malcolm,

well if I would like to point out that, for instance, Haskell exists for a lot more than 10 years now, and that, while the language per se rocks, and there are cool tools (cabal) and libraries (list, Set, Map), there still isn't even a mail client library, I wonder whom to escalate this to, and who is going to do something about it.

I understand some parties wish to avoid success at all costs, while others, commercial users, benefit from the edge haskell gives them already and which probably can help themselves in case of, again, for instance a missing mail client library.

And then there is the ones like me, which also want to benefit from the edge Haskell gives them over users of other languages and want to develop Real World Apps and who cannot easily help themselves in case of a missing mail client library.

So while there are many aspects of the future of haskell, who effectively is it that steers the boat?

Günther

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org mailto:Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

On 10/29/10 2:33 AM, Gregory Crosswhite wrote:

Also, this is a complete aside but what the heck. :-)

Has anyone else been driven crazy by the way that Java code and libraries are documented? It seems like whenever I try to figure out how to use a piece of Java code, the functionality is spread out over a huge collection of classes and methods so that it is impossible to figure out where things actually happen and how the code is supposed to be used. Am I correct to perceive this as a general trend in Java, or is it just the projects that I looked at and/or my lack of experience in how Java sources and libraries are organize?

I've certainly noticed that, though JavaDoc does (usually) give links so you can follow the bread crumbs. Honestly, I think a big part of this isn't documentation practices so much as it is the expression problem. For a lot of the problems I tackle, the OO model is not appropriate for capturing program structure. Pairing this with Java's requirement of one class per file means that the actual functionality itself is spread out across a huge collection of classes and methods. The JavaDoc is just working with what it gets. This is one of the (many) reasons I prefer Haskell: the structure of Haskell programs matches the structure of the problems I need to solve (or at least, how I think about them). -- Live well, ~wren

On 29/10/2010, at 7:33 PM, Gregory Crosswhite wrote:

Also, this is a complete aside but what the heck. :-)

Has anyone else been driven crazy by the way that Java code and libraries are documented? It seems like whenever I try to figure out how to use a piece of Java code, the functionality is spread out over a huge collection of classes and methods so that it is impossible to figure out where things actually happen and how the code is supposed to be used. Am I correct to perceive this as a general trend in Java, or is it just the projects that I looked at and/or my lack of experience in how Java sources and libraries are organize?

Talking about documentation in the 3rd year software engineering paper I teach, I give JavaDoc as an example of what not to do. I give R as an example of something that works quite well. It's *examples* that make the difference. One thing I will say for the JavaMail specification is that it has some useful examples.

On 29 Oct 2010, at 07:33, Gregory Crosswhite wrote:

Also, this is a complete aside but what the heck. :-)

Has anyone else been driven crazy by the way that Java code and libraries are documented? It seems like whenever I try to figure out how to use a piece of Java code, the functionality is spread out over a huge collection of classes and methods so that it is impossible to figure out where things actually happen and how the code is supposed to be used. Am I correct to perceive this as a general trend in Java, or is it just the projects that I looked at and/or my lack of experience in how Java sources and libraries are organize?

Yes I had a bit of a rant about that in my blog recently http://gaiustech.wordpress.com/2010/09/27/api-documentation/ It's by no means only Java; automated documentation generators are the problem. They add no more value than a smart editor could give you anyway, or reading the comments. You need an API reference *and* sample code *and* a high level introduction and explanation of intent to count as "documentation" in my book. Cheers, G