Re: Do C++ and Java professionals use UML??
On 07/26/2012 06:16 PM, Gene Wirchenko wrote:
On Thu, 26 Jul 2012 11:35:01 +0200, Robert Klemme
<shortcutter@googlemail.com> wrote:
On 23.07.2012 22:53, Gene Wirchenko wrote:
On Mon, 23 Jul 2012 21:11:29 +0200, Robert Klemme
<shortcutter@googlemail.com> wrote:
Why would one use this class? [If I am a newbie, I may not
know.]
I think it the most important thing. If one does not know why
one would use a class, why even bother?
IMHO the class documentation is reference material which should provide
the basic facts so I can decide myself whether the class is appropriate
for the use case at hand or not. Learning to judge that is part of the
process of learning to program. That should not be piggybacked on
reference documentation.
I have seen this botched in intro classes where recursion is
introduced. All too often the example used is factorial which is much
more quickly and clearly solved using iteration. The student gets the
impression that it is overly complicated and never bothers with it.
Yeah, but the cases where recursion makes the code simpler are typically
more complex algorithms (backtracking for example). I suspect all
methods which can be converted into a loop via tail recursion
optimization are as simple as factorial.
Often class documentation in the Java stdlib does contain usage
examples. But for fundamental classes like String there are so many
potential use cases that you cannot really cover them all in the class doc.
One example of the method in use is a problem?
Many methods do not make much sense alone (for example, Map's
containsKey()). Then the question is where should the example be placed
etc.
I think we have a quite different expectation towards JavaDoc. For me
it's reference material, so I expect to get formal information (allowed
arguments, semantics) while you seem to be more concerned with providing
information that helps learn the language and std library. I think that
information is better covered in a tutorial or other type of document
(maybe even a book) and it would get in your way when working with the
library. Because then the introductory information easily gets in your
way and you need to look longer for the important information.
I am not sure though whether I agree that the situation is as bad as
your list makes it sound. For example, java.util.* is pretty well
documented IMHO.
One effect that I have noticed with things like this is that a
newbie struggles. Someone who already knows does not see a problem.
He is already past it. so it rarely gets addressed.
But if it were such a big issue for a large number of people learning
Java I am pretty sure it would be addressed. So I conclude the
situation cannot be as bad as you observe it.
Kind regards
robert