RE: [MO-java-dev] Java Doc

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Tim,

I agree with almost all you have said. Here are a few comments though:

1/ Test case as documentation is good if you are yourself developing the
framework. If you're simply the user you probably don't want to bother
finding the test sources, installing them on your system and trying to
figure out some part of the implementations. What would be useful would
to copy the sample (aka the unit test :-)) in the generated javadoc (but
that's not very easy to do - I have thought about doing this for a
while).

2/ If I take a class named Control somewhere, I agree with you that I
don't want to know that getType() returns the type. However what I do
want to know is what a Control is. In what context is it used. The unit
tests will *not* tell me this, they simply tell me how to use it. But I
still lack the class level doc. So I think there is some margin for
useful doc. In mock objects, we need to explain to the user what an
Expectation is for example, even better with an example.

3/ You may be surprised that one of the rule I have given on my project
at work was to have javadoc for every single method! Even for the
getXXX() or setXXX() ones. The reasons are :

- our developers are not yet writing fined-grained unit tests

- writing comments still force you to ponder design ideas (in a lesser
way than writing unit tests *but* still better than nothing, and persons
still find it easier to write comments rather than refactor a piece of
code because it is badly written and thus cannot be easily tested using
mock objects)

- if we give the rule "only write comment where it is necessary" then
the result is obvious (this is proven stuff for us - we did it) :
nothing will get written. Moreover we cannot automatically check that
rule.

Thus the result is that we're using checkstyle with the javadoc checks
on and the build fails if javadoc is missing. At least it forces us not
to be lazy, think a bit about what our code does and *sometimes*
produces interesting comments! :-)

One more: we're working in a distributed team ... thus can't rely on
oral knowledge. 

I think (as Ted pointed out) that a lot of XP teams do not write
comments because they don't feel the need. The work in close and small
teams and are able to follow quite closely what's going on. In larger
groups, distributed groups, and frameworks, you really have "clients"
that need to understand the code that you have written. Tests are nice
but are really fine-grained and are only interesting if you already
understand the bigger picture, that is :
- overall architecture first (this is the overview.html and package.html
javadoc for example - if we're staying javadoc land)
- how the objects are linked together (that's the top level class
comments)

I agree that method level comments are useful only sporadically.

Time to go to bed ... :-)

Cheers,
-Vincent

> -----Original Message-----
> From: moc...@li...
> [mailto:moc...@li...] On Behalf Of
Tim
> Mackinnon
> Sent: 26 August 2002 19:52
> To: Mockobjects-Java-Dev
> Subject: [MO-java-dev] Java Doc
> 
> Hmmm - have seen this before at OTI where (when I was there many years
> ago)
> we were required to put a method comment on public methods (and this
was
> all
> highly disciplined people) - and generally the method and names of the
> paramters were all that was needed. I often wanted to write "Does just
as
> it
> says on the tin"!
> 
> If not - renaming the method is usually a better fix than writing the
doc?
> 
> The only type of comment needed might be the range of the paramaters -
but
> then I think that the tests of a method more reliably document this.
And
> if
> you've got tests - why create more work by duplicated them in non-
> executable
> code? Maybe a tool to autogenerate the comments would be an answer for
> those
> who don't have good IDE's. We could just ship a little program with
the
> source code - DocGenerator.exe (that would be more useful).  Of course
-
> there is sometimes a policy decision, or workaround that does require
> documentation, and in this respect Ted is right. But for the mindless
> stuff - docgenerator may be a better answer?
> 
> 
> For example -  I have just randomly picked a Java class from the
javadoc
> that I didn't know anything about "Control". The constructor has:
> 
> Control(Control.Type type)
>           Constructs a Control with the specified type.
> 
> and methods:
> 
> Control.Type getType()
>           Obtains the control's type.
> 
> String toString()
>           Obtains a String describing the control type and its current
> state.
> 
> 
> This isn't very useful is it??? There are lots of examples of this -
> although once in a while there is a useful doc e.g. (InputStream)
> 
> public abstract int read()
>                   throws IOExceptionReads the next byte of data from
the
> input stream. The value byte is returned as an int in the range 0 to
255.
> If
> no byte is available because the end of the stream has been reached,
the
> value -1 is returned. This method blocks until input data is
available,
> the
> end of the stream is detected, or an exception is thrown.
> 
> Anyway - I'll stop now :-)
> 
> 
> Tim
> 
> -----Original Message-----
> From: Shellman, Joel [mailto:Joe...@su...]
> Sent: 26 August 2002 18:27
> To: tim...@po...
> Subject: RE: [MO-java-dev] Volunteer: Ted Husted
> 
> 
> > I wouldn't want to see the mock objects project go the way of the
SUN
> > JavaDoc which is quite frankly useless!!! At the method level the
doc
> simply
> > states everything that the method signature gives - what a waste of
> energy.
> 
> How ironic. I was just reading Sun's guidelines for writting JavaDoc
and
> they specifically stated that the JavaDoc should not state what is
already
> in the method signature.
> 
> Joel Shellman
> 
> 
> ---
> Incoming mail is certified Virus Free.
> Checked by AVG anti-virus system (http://www.grisoft.com).
> Version: 6.0.381 / Virus Database: 214 - Release Date: 02/08/2002
> 
> ---
> Outgoing mail is certified Virus Free.
> Checked by AVG anti-virus system (http://www.grisoft.com).
> Version: 6.0.381 / Virus Database: 214 - Release Date: 02/08/2002
> 
> 
> 
> -------------------------------------------------------
> This sf.net email is sponsored by: OSDN - Tired of that same old
> cell phone?  Get a new here for FREE!
> https://www.inphonic.com/r.asp?r=sourceforge1&refcode1=vs3390
> _______________________________________________
> Mockobjects-java-dev mailing list
> Moc...@li...
> https://lists.sourceforge.net/lists/listinfo/mockobjects-java-dev