It is not JavaDoc of the single class/interface that could give you the bigger picture.
It's the documentation of used patterns/models/architectures that helps you to master the code.
IMHO JavaDoc is useful for the API of interfaces, rarely for classes.
I was really talking about the bigger picture in terms of what the class/method/block of code inside a method is for. You're right to say it won't give you the "big picture" on it's own in terms of the entire system, at least, one class taken isolation isn't likely to. But if the comments are well-written at the class level it *should* help you understand where that class fits into the bigger picture, which is very valuable, so in a sense it can help give you the bigger picture, but certainly it isn't likely to do it on it's own.
* THE CODE IS NEVER AS CLEAR AS YOU BELIEVE IT IS.
In this case, I don't think that JavaDoc comment would help.
I think it can if the comments are well-written. My point is that trying to understand code can be difficult, but if you have well-written comments then at least you can say "ok, I know what the code is supposed to do, so now I can try and parse it and get the details from it".
I can only speak for me, but I know that looking at other peoples' code gives me a headache, and in fact, looking at my own code some time later does too, not because either is poorly-written but just because I find it taxing to get the gist of what's going on from just the code. I know that's a bit unusual for a developer, and it's not that I can't do it, in fact I do it all the time, but I find my life is considerably easier and my brain hurts less when there's comments that say "this code does X, Y and Z for reasons A, B and C", and then the code makes a whole lot more sense as I'm mentally parsing it.
If you can understand the code without the comments, you're doing a good job.
When I read the code I rarely check the docs.
I always try to figure out what I'd do in the same situation and this drives me in the investigation.
I have a rather high success ratio in understanding code, etiher well written or bad written.
But how do you "figure out what you'd do in that same situation" if you aren't sure what's *supposed* to be happening? I come at things just the opposite: the comments tell me what's going on, then the code fills in the details of the process.
For me, if you can't put into plain English what the code is supposed to do, it's probably not good code. Now, this does assume the comments are kept current and and are meaningful in the first place, neither of which is a given in my experience (and I suspect yours), but assuming both those things are true, I think the comments enhance the code considerably.
As I pointed out, several aspects of a system are not well documentable with JavaDoc.
I think that's a fair point. I've seen (and have written) javadoc that went far and beyond what Javadoc typically does... just check out the javadoc for Apache Commons Digester... there's probably more there than should be, in terms of what javadoc was meant for, but it's useful none the less, so javadoc *can* I think comment those "undocumentable" aspects of a system... but I don't disagree if you say it's not the best tool for the job.
I would add poor QA people too to the list.
Anyway, is not good JavaDoc that would increase maintainability of a system.
You could always write wonderful javadoc for very stupid classes and you will go into troubles when it's time to change something.
Hehe, if you're lucky enough to have QA folks checking your javadoc then I applaude your organization! :)
Are you saying that good javadoc *can't* increase the maintainability of a aystem? I would strongly disagree with that statement. I think *any* GOOD documentation enhances maintainability. If you're instead saying that javadoc isn't the be-all and end-all of documentation, that I would certainly agree with.
I also don't like the argument, which I've heard plenty of times over the years, that commenting code isn't a good idea because the comments never keep up with the code and therefore are more harm then good. I'm not at all disagreeing with that fact that it's a real problem, I've seen it many times, and it's a hassle. But that's nothing but laziness IMO. Yes, it's more work to keep the comments and code in sync, but I view it as a very worthwild exercise that gives a substantial return on the time investment to do it.