[Haskell-cafe] who's in charge?
Gaius Hammond
gaius at gaius.org.uk
Sun Oct 31 18:19:28 EDT 2010
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
More information about the Haskell-Cafe
mailing list