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