[Haskell-cafe] who's in charge?

[wren ng thornton]

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