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

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

Vincent - very interesting - its both good and bad:

1. I have never seen this libary and new nothing about it so it was a good
example to give to me
2. The first page was very good - the packages descriptions were excellent -
the paragraph at the bottom of the page is duplicate of the top though (so
REFACTOR)
3. I clicked on the first package - the first paragraph is yet again another
copy of the aforementioned one... boy I hope the goal of the project doesn't
change
4. The interface descriptions are ok, but you know what? If they just had
better names in the first place I wouldn't need the text? Hmmmm Converter -
I wonder what that does???? The text tells me so much... in fact the first
few words give it away "Gneral purpose data type converter... " - gosh if
they had called it DataTypeConverter I would really know what it was...???
DynaBean and DynaClass are more obscure maybe the docs help (but hey we've
started writing docs now so we better keep going... Joke :-) I would still
try and think of a better name though
5. Class summaries - I got bored reading those - the names pretty much did
it for me
6. ConversionExpection - WOW this comment really really made it very clear
to me... ;-)
7. The Overview - ok now we're talking - leave out 3-6 and get to this baby,
thats more like it.. but you know what the examples make me start to feel
nervous... Are they still up to date? If we refactor a method name would the
docs still be up to date???? I had a quick look and it looks like they are
but really a hyperlink (or an inline inclusion of a real test method would
be so much more believable) would be better.

8. Although the section after "RowSetDynaClass (Disconnected ResultSet as
DynaBeans)" has a non function full paragraph hyperlink
9. The sections after this they were obviously running out of steam and the
formatting gets much worse and the content begins to border on the
obvious...

Conclusion -

Package descriptions seem like a great idea along with a 1 or 2 paragraph
description (but don't replicate it everywhere). The Introduction with
example snippets are great - link the real examples (and don't pretend to
have the full example in the text). Keep it tight and don't get too carried
away as you run out of steam near the end.

So yes Vincent - lets pick "cheap" documentation, and get the high value
stuff

Tim

p.s. Really interestingly, one of the Thoughtworks teams finally took a long
standing idea and generated docs for a class where they parsed the test
names for a class and outputed:

ClassX is an object that:
- Handles Zero Items Added
- Handles N Items With a Null
- Throw An Exception With An Empty List
- Allows Mixed Object Addition
etc.

Guess what - its all based on writing tests with good names and with a bit
of creativity you get pretty good docs and are encouraged to write good test
names... now thats Interesting dont you thing?

> -----Original Message-----
> From: moc...@li...
> [mailto:moc...@li...]On Behalf Of
> Vincent Massol
> Sent: 04 June 2003 07:53
> To: 'Tim Mackinnon'; moc...@li...
> Cc: 'Mockobjects-Java-Dev'
> Subject: RE: [MO-java-dev] Javadoc is now online...
>
>
>
>
> > -----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
>
>
>
>
> -------------------------------------------------------
> This SF.net email is sponsored by:  Etnus, makers of TotalView, The best
> thread debugger on the planet. Designed with thread debugging features
> you've never dreamed of, try TotalView 6 free at www.etnus.com.
> _______________________________________________
> 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