RE: [MO-java-dev] Javadoc is now online...

[Vincent M. <vm...@pi...>]

> -----Original Message-----
> From: Tim Mackinnon [mailto:tim...@po...]
> Sent: 04 June 2003 01:41
> To: Vincent Massol; moc...@li...
> Cc: 'Mockobjects-Java-Dev'
> Subject: RE: [MO-java-dev] Javadoc is now online...
> 
> oooh catty.... I can feel the scratches ;-)

;-)

> 
> Yes - I personally think that docs are a crutch for writing bad code. 

I won't disagree with that. Writing good doc is for sure as hard as
writing good code :-)

> I've
> tried both and run the experiments and found that if I just wrote
better
> code, had better method names, better variable names and better
examples
> and
> tests - then the documents needed were very rudimentary. Yes its hard
-
> but
> it pays off (the result being better code ).

Sure but don't say the MockObjects framework is well documented! :-)

> 
> I would prefer people spend effort on a Q&A or a short article than
write
> java doc - maybe its a smalltalk thing - once I've got past the
> introduction
> and seen an example I'm quite happy to browse working code that I know
is
> up
> to date.

You may be missing the overview.html and package.html part of javadoc
which is probably the most fundamental one.

> 
> We seem to disagree on this Vincent - but for all of your feedback on
> requests for documentation I have tried to diligently go back to the
code
> and fix what was a problem there in the first place.

Sure and I thank you for that! :-)

Several things:
- first, I personally don't care about the javadoc as I am a
"power-user" of MockObjects and I have the code ready on my machine,
etc. 
- Someone asked for it and I have uploaded it for that person. This is
quite a logical request seen that there is almost no doc on MockObjects
or Dyna Mocks and people are used to getting some information from the
javadoc. 
- Javadoc can be very good. Have a look at the one for BeanUtils for
example: http://jakarta.apache.org/commons/beanutils/api/index.html
- I agree that the following is useless:

/**
 * @return the name
 */
public String getName()
{
[...]

and I would probably agree that there is no need to document this
method. 

Some thoughts:
 
1/ I think you consider javadoc as a way to document what the logic of a
method does whereas I consider javadoc as a way to explain how a given
method fit in its environment, i.e. what's the purpose of the method is
and how it relates to the other concepts of the
application/frwk/whatever.

2/ Public API (not public methods) cannot be changed at will. A change
to a public API breaks all its users. Thus, once you have decided on a
name you cannot change it easily and you need to go through a long
process. For example, the getName() above may not be explicit enough and
should really be called getCustomerName() but I can't change it. So a
comment saying that we are talking about a customer name might be
helpful.

3/ For me the value of some piece of code is much more than the few
lines themselves. It is:
- has it been tested (i.e. suite of tests)
- does it follow some well-defined coding conventions, i.e is it easy to
read
- is it enough documented so that users/extender can understand it (can
be javadoc, unit tests, etc) and is the documentation readily accesible

4/ What would be nice is a doclet that takes the test code and put it in
javadoc format, next to the behavior tested. Most people will not go to
the source to get the doc so we need a way to simply publish the unit
tests on the doc web site.

> 
> But maybe we do need some documentation that says:
> 
> - How to install it
> - Which example to look at first
> - What to do next
> - How to read the code and use it as the documentation

yep. These are all good topics for documentation.

Now, I'll shut up because what we need are not words but actions and I
am currently overwhelmed...

Thanks Tim!
-Vincent

> 
> 
> Tim
> 
> > -----Original Message-----
> > From: moc...@li...
> > [mailto:moc...@li...]On Behalf
Of
> > Vincent Massol
> > Sent: 03 June 2003 08:59
> > To: moc...@li...
> > Cc: 'Mockobjects-Java-Dev'
> > Subject: [MO-java-dev] Javadoc is now online...
> >
> >
> > FWIW, I've put the javadoc online:
> >
> > http://www.mockobjects.com/wiki/Javadocs
> >
> > Note: The MockObjects team thinks that javadoc is not needed and
that
> > good code should generally not need javadoc (i.e. it should be
> > sufficiently expressive by itself). Thus you will find that this
javadoc
> > will not give you any explanation at all! In order to get
explanation
> > you are invited to read the code :-)
> >
> > Thanks
> > -Vincent
> >
> >
> >
> > -------------------------------------------------------
> > This SF.net email is sponsored by: eBay
> > Get office equipment for less on eBay!
> > http://adfarm.mediaplex.com/ad/ck/711-11697-6916-5
> > _______________________________________________
> > Mockobjects-java-dev mailing list
> > Moc...@li...
> > https://lists.sourceforge.net/lists/listinfo/mockobjects-java-dev
> >
> > ---
> > Incoming mail is certified Virus Free.
> > Checked by AVG anti-virus system (http://www.grisoft.com).
> > Version: 6.0.487 / Virus Database: 286 - Release Date: 01/06/2003
> >
> ---
> Outgoing mail is certified Virus Free.
> Checked by AVG anti-virus system (http://www.grisoft.com).
> Version: 6.0.487 / Virus Database: 286 - Release Date: 01/06/2003