Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #16387

Re: Do C++ and Java professionals use UML??

Path csiph.com!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!news.musoftware.de!wum.musoftware.de!fu-berlin.de!uni-berlin.de!individual.net!not-for-mail
From Robert Klemme <shortcutter@googlemail.com>
Newsgroups comp.lang.java.programmer
Subject Re: Do C++ and Java professionals use UML??
Date Thu, 26 Jul 2012 11:35:01 +0200
Lines 98
Message-ID <a7chacFoblU1@mid.individual.net> (permalink)
References <lluh08lnc655tiu1mo4972oddebc3ciss2@4ax.com> <slrnk0i1f5.fbk.fredrik@scout.jonson.org> <a6subnFf45U1@mid.individual.net> <jucbq7$lg6$1@localhost.localdomain> <UML-20120720213658@ram.dialup.fu-berlin.de> <a6u2riF3fuU1@mid.individual.net> <m8dp08hrsk48p3kj5g47uso1gpp1qrh603@4ax.com> <500cbc5d$0$295$14726298@news.sunsite.dk> <a74c3mF476U1@mid.individual.net> <i50r08hjiebe152pdeot546psfefk432vh@4ax.com> <a75lv5F11vU1@mid.individual.net> <3qcr08lkpvcmhe0drpffhegusd6k2a1670@4ax.com>
Mime-Version 1.0
Content-Type text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding 7bit
X-Trace individual.net y03hovRIVTksBUvlv69iWAWSksJ+E1Z6mF/lHCKM5XSvYLIQ/oAfxfGz2uz7jgVLs=
Cancel-Lock sha1:vues8mH5M+8tTEyjuqSmCdFuMfw=
User-Agent Mozilla/5.0 (Windows NT 6.0; WOW64; rv:14.0) Gecko/20120713 Thunderbird/14.0
In-Reply-To <3qcr08lkpvcmhe0drpffhegusd6k2a1670@4ax.com>
Xref csiph.com comp.lang.java.programmer:16387

Show key headers only | View raw

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 
programming it's better to have proper introductory material in a 
narrative style.  That should explain what the difference between a 
O(n), O(log(n)) and O(1) access time is.  That information *is* given in 
class documentation.

>       How is this class related to others?  What other classes would be
> used with this class, and why?  [What is the structure of classes?
> What is their interrelation?]

That can be pretty good extracted from the hyperlinking of method 
arguments, return types and the "Use" section and following to 
implemented interfaces and then down to implementing classes.

>       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.

>       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.

>       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.

>       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.

>       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.

Kind regards

	robert


-- 
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/

Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

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