Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.java.programmer > #16391
| From | Gene Wirchenko <genew@ocis.net> |
|---|---|
| Newsgroups | comp.lang.java.programmer |
| Subject | Re: Do C++ and Java professionals use UML?? |
| Date | 2012-07-26 09:16 -0700 |
| Organization | A noiseless patient Spider |
| Message-ID | <6sq218p9vfg1m2fgg5pm8sthhdot288mia@4ax.com> (permalink) |
| References | (7 earlier) <a74c3mF476U1@mid.individual.net> <i50r08hjiebe152pdeot546psfefk432vh@4ax.com> <a75lv5F11vU1@mid.individual.net> <3qcr08lkpvcmhe0drpffhegusd6k2a1670@4ax.com> <a7chacFoblU1@mid.individual.net> |
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:
>
>>> Hmmm. I can't say I was really lacking that much. In which areas do
>>> you see deficiencies? Or: what would you add?
>>
>> I would add the following. The square-bracketed end notes give
>> my rationale.
>>
>> Why would one use this class? [If I am a newbie, I may not
>> know.]
>
>I do not think class documentation is responsible to cover this;
>actually I'd consider it rather harmful than helpful. If one is new to
I think it the most important thing. If one does not know why
one would use a class, why even bother?
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.
[snip]
>> What does this class have in common with other classes as to its
>> properties, methods, exceptions, etc.? Some classes are very similar
>> -- I am thinking of readers and writers -- but address slightly
>> different things. I would like to see something like "Readers
>> generally have the following properties, methods, exceptions, etc.:"
>> followed by the details of the in-common characteristics. If a class
>> broke with the commonality, that should be documented in the class:
>> "<foo> breaks with <method> doing <doesthis1>, instead doing
>> <doesthis2>." [I do not want to have to read the same thing several
>> times and possibly miss the time or times when a class behaves
>> differently]
>
>I am getting the impression that what you are asking is customization to
>your specific reading habits. Others might be better off with the
>current state of affairs. At least I do not see a reasoning why that
>should be better as the general case.
No. There is a lot of material. Why shouldn't it be organised
to cut down the amount of reading? Put the common stuff together;
this is rather like a procedure in code where we do not keep the
common code separate.
>> For each property, WHAT ARE THEIR VALID VALUES? (Giving just the
>> property name is inexcusable.) [I should not have to guess. A name
>> is not documentation.]
>
>Whether passing null is allowed or not is probably one of the more
>frequent omissions of JavaDoc, I agree.
There is more than that. If parameter is an integer, is a
negative value allowed? In some contexts, it might be obvious that it
is (or is not), but in some, who knows? Documentation should answer
that.
>> For each method, what are the parameters and the return value,
>> AND WHAT ARE THEIR VALID VALUES? (Giving just the parameter name or
>> return type is inexcusable.) Give at least one non-trivial example of
>> its use including what the correct result is. [I should not have to
>> guess. A name is not documentation. I want to be able to check that
>> I understand what a method does.]
>
>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?
>> If an unusual term is used in a class's documentation, define
>> that term. [I recall a string class having the term "subsequence" in
>> its documentation. Combined with no examples, it meant that I could
>> not follow that section at all.]
>
>Are you referring to
>http://docs.oracle.com/javase/6/docs/api/java/lang/CharSequence.html ?
>I find that pretty comprehensive.
No. Yes, that one is better.
>> And this should all be very easy to find. Documentation that can
>> not be easily found might as well not exist.
>
>Well, modern IDE's typically link to JavaDoc and will even synthesize
>JavaDoc from source code (Eclipse does it when hovering over a method
>call or type name).
>
>> None of these points need be very long, but their absence can
>> severely cripple someone trying to use the class.
>
>Thank you for the list! This all can be done in JavaDoc. I thought you
>were missing documentation independent from individual classes and
>explaining concepts.
>
>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.
Sincerely,
Gene Wirchenko
Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Do C++ and Java professionals use UML?? "Ramon F. Herrera" <ramon@conexus.net> - 2012-07-19 13:09 -0700
Re: Do C++ and Java professionals use UML?? Daniel Pitts <newsgroup.nospam@virtualinfinity.net> - 2012-07-19 14:12 -0700
Re: Do C++ and Java professionals use UML?? Ivan The Not-So-Bad <1suf41n@yahoo.com> - 2012-07-19 21:47 +0000
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-19 18:00 -0400
Re: Do C++ and Java professionals use UML?? Lew <lewbloch@gmail.com> - 2012-07-19 14:35 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-19 17:58 -0400
Re: Do C++ and Java professionals use UML?? David LaRue <huey.dll@gte.net> - 2012-07-19 22:22 +0000
Re: Do C++ and Java professionals use UML?? Leif Roar Moldskred <leifm@dimnakorr.com> - 2012-07-19 17:41 -0500
Re: Do C++ and Java professionals use UML?? Roedy Green <see_website@mindprod.com.invalid> - 2012-07-19 23:29 -0700
Re: Do C++ and Java professionals use UML?? Fredrik Jonson <fredrik@jonson.org> - 2012-07-20 07:16 +0000
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-20 13:39 +0200
Re: Do C++ and Java professionals use UML?? Martin Gregorie <martin@address-in-sig.invalid> - 2012-07-20 19:33 +0000
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-21 00:02 +0200
Re: Do C++ and Java professionals use UML?? Patricia Shanahan <pats@acm.org> - 2012-07-20 15:22 -0700
Re: Do C++ and Java professionals use UML?? Martin Gregorie <martin@address-in-sig.invalid> - 2012-07-20 23:45 +0000
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-20 19:54 -0400
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-21 12:15 +0200
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-07-21 19:21 +0200
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-22 19:26 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-22 22:52 -0400
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-23 09:17 +0200
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-23 10:03 -0700
Re: Do C++ and Java professionals use UML?? markspace <-@.> - 2012-07-23 10:51 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-23 11:42 -0700
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-23 21:11 +0200
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-23 13:53 -0700
Re: Do C++ and Java professionals use UML?? "John B. Matthews" <nospam@nospam.invalid> - 2012-07-23 21:00 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-23 18:48 -0700
Re: Do C++ and Java professionals use UML?? "John B. Matthews" <nospam@nospam.invalid> - 2012-07-24 15:44 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-24 13:47 -0700
Re: Do C++ and Java professionals use UML?? Lew <lewbloch@gmail.com> - 2012-07-24 14:18 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-24 14:38 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-24 18:36 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-24 16:32 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-24 20:20 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 10:10 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 13:58 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 13:38 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 18:42 -0400
Re: Do C++ and Java professionals use UML?? Lew <noone@lewscanon.com> - 2012-07-25 06:44 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 10:14 -0700
Re: Do C++ and Java professionals use UML?? Jim Gibson <jimsgibson@gmail.com> - 2012-07-25 15:05 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 16:07 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 19:35 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 17:33 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 21:00 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-26 09:06 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-26 13:04 -0400
Re: Do C++ and Java professionals use UML?? Patricia Shanahan <pats@acm.org> - 2012-07-26 09:36 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-26 13:10 -0400
Re: Do C++ and Java professionals use UML?? Patricia Shanahan <pats@acm.org> - 2012-07-26 11:01 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-26 14:47 -0400
Re: Do C++ and Java professionals use UML?? David Lamb <dalamb@cs.queensu.ca> - 2012-07-26 17:13 -0400
Re: Do C++ and Java professionals use UML?? Patricia Shanahan <pats@acm.org> - 2012-07-27 09:05 -0700
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-08-04 10:17 +0200
Re: Do C++ and Java professionals use UML?? Patricia Shanahan <pats@acm.org> - 2012-08-04 07:45 -0700
Re: Do C++ and Java professionals use UML?? "John B. Matthews" <nospam@nospam.invalid> - 2012-08-05 10:50 -0400
Re: Do C++ and Java professionals use UML?? Patricia Shanahan <pats@acm.org> - 2012-08-05 08:41 -0700
Re: Do C++ and Java professionals use UML?? "John B. Matthews" <nospam@nospam.invalid> - 2012-08-06 21:23 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-08-06 22:11 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-08-06 22:01 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-08-06 21:58 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-27 09:30 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-26 10:57 -0700
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-08-03 00:41 +0200
Re: Do C++ and Java professionals use UML?? Lew <lewbloch@gmail.com> - 2012-08-02 16:48 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-08-02 19:52 -0400
Re: Do C++ and Java professionals use UML?? Lew <lewbloch@gmail.com> - 2012-08-02 17:33 -0700
Re: Do C++ and Java professionals use UML?? Lew <noone@lewscanon.com> - 2012-07-25 06:41 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 10:38 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-24 18:42 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-24 16:35 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-24 20:07 -0400
Re: Do C++ and Java professionals use UML?? markspace <-@.> - 2012-07-24 17:36 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 10:22 -0700
Re: Do C++ and Java professionals use UML?? markspace <-@.> - 2012-07-25 10:57 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 13:41 -0700
Re: Do C++ and Java professionals use UML?? markspace <-@.> - 2012-07-25 13:44 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 14:34 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 18:46 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 16:10 -0700
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-07-30 14:59 +0200
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-30 19:55 -0400
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-08-02 23:41 +0200
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-08-02 18:31 -0400
Re: Do C++ and Java professionals use UML?? markspace <-@.> - 2012-07-25 15:54 -0700
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 16:11 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 19:30 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-25 18:49 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-25 16:13 -0700
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-26 11:35 +0200
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-26 09:16 -0700
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-27 13:21 +0200
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-27 09:16 -0700
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-27 21:02 +0200
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-27 13:47 -0700
Re: Do C++ and Java professionals use UML?? markspace <-@.> - 2012-07-27 13:51 -0700
Re: Do C++ and Java professionals use UML?? David Lamb <dalamb@cs.queensu.ca> - 2012-07-27 17:11 -0400
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-28 18:36 +0200
Re: Do C++ and Java professionals use UML?? Eric Sosman <esosman@ieee-dot-org.invalid> - 2012-07-28 13:50 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-29 15:24 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-23 19:46 -0400
Re: Do C++ and Java professionals use UML?? Gene Wirchenko <genew@ocis.net> - 2012-07-23 18:49 -0700
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-23 22:59 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-23 19:40 -0400
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-20 19:51 -0400
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-07-21 19:16 +0200
Re: Do C++ and Java professionals use UML?? Robert Klemme <shortcutter@googlemail.com> - 2012-07-21 19:49 +0200
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-07-23 03:28 +0200
Re: Do C++ and Java professionals use UML?? Leif Roar Moldskred <leifm@dimnakorr.com> - 2012-07-20 03:03 -0500
Re: Do C++ and Java professionals use UML?? Arne Vajhøj <arne@vajhoej.dk> - 2012-07-20 19:46 -0400
Re: Do C++ and Java professionals use UML?? Wanja Gayk <brixomatic@yahoo.com> - 2012-07-21 18:59 +0200
Re: Do C++ and Java professionals use UML?? R kamalakkannan <kamalakkannan.ney@gmail.com> - 2012-08-02 01:57 -0700
csiph-web