mockobjects-java-dev

[MO-java-dev] Java Doc

[Tim M. <tim...@po...>]

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

Re: [MO-java-dev] Java Doc

[Nat P. <nat...@b1...>]

Just to stick my oar in... the mock objects library is really divided
into two parts, the core com.mockobjects package, which contains the
expectation classes and MockObject base class, and then the packages of
classes that mock actual APIs.  

The com.mockobjects package is so simple that I have not found a need
for documentation beyond the source and tests.  The other packages
implement predefined interfaces (already documented by Sun, for
example), and add setExpected... and setup... methods, the names of
which follow strict conventions and are derived from the method and
parameter names defined by the API.

The steepest part of the learning curve, in my experience, was learning
the naming conventions and how to apply the com.mockobject classes to
the mocking of my own interfaces.  The source to the mocked API packages
was useful guidance.

So, perhaps it would be better to write some tutorial documents,
explaining the naming conventions and how to use the classes in
com.mockobjects to create new mocks.  There already is a document on
naming conventions, but it is quite terse and the link is tucked away in
the corner of the mock objects home page.

Cheers,
	Nat. 

-- 
Dr. Nathaniel Pryce, Technical Director, B13media Ltd.
Studio 3a, 22-24 Highbury Grove, London N5 2EA, UK
http://www.b13media.com

RE: [MO-java-dev] Java Doc

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

+1 to that. 

But we also need an "architecture" document or a "user guide" document
that explains what an Expectation is (the probe notion), how it works,
that there is a core and what it provides, etc. This in addition better
naming conventions. I think the original paper is nice but too complex
to understand for a newcomer. We need something easier ...

-Vincent

> -----Original Message-----
> From: moc...@li...
> [mailto:moc...@li...] On Behalf Of
Nat
> Pryce
> Sent: 26 August 2002 22:06
> To: Mockobjects-Java-Dev
> Subject: Re: [MO-java-dev] Java Doc
> 
> Just to stick my oar in... the mock objects library is really divided
> into two parts, the core com.mockobjects package, which contains the
> expectation classes and MockObject base class, and then the packages
of
> classes that mock actual APIs.
> 
> The com.mockobjects package is so simple that I have not found a need
> for documentation beyond the source and tests.  The other packages
> implement predefined interfaces (already documented by Sun, for
> example), and add setExpected... and setup... methods, the names of
> which follow strict conventions and are derived from the method and
> parameter names defined by the API.
> 
> The steepest part of the learning curve, in my experience, was
learning
> the naming conventions and how to apply the com.mockobject classes to
> the mocking of my own interfaces.  The source to the mocked API
packages
> was useful guidance.
> 
> So, perhaps it would be better to write some tutorial documents,
> explaining the naming conventions and how to use the classes in
> com.mockobjects to create new mocks.  There already is a document on
> naming conventions, but it is quite terse and the link is tucked away
in
> the corner of the mock objects home page.
> 
> Cheers,
> 	Nat.
> 
> --
> Dr. Nathaniel Pryce, Technical Director, B13media Ltd.
> Studio 3a, 22-24 Highbury Grove, London N5 2EA, UK
> http://www.b13media.com
> 
> 
> 
> 
> -------------------------------------------------------
> 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

Re: [MO-java-dev] Java Doc

[Jeff M. <je...@mk...>]

On Mon, 2002-08-26 at 22:06, Nat Pryce wrote:
> Just to stick my oar in... the mock objects library is really divided
> into two parts, the core com.mockobjects package, which contains the
> expectation classes and MockObject base class, and then the packages of
> classes that mock actual APIs.  
> 
Actual there's now three. The alt tree which provides mockable versions
of unmockable classes.

This probably needs some java doc as it may not be totally apparent what
they're for. (See earlier discussion with Tim re alt.java.io.File)


> The com.mockobjects package is so simple that I have not found a need
> for documentation beyond the source and tests.  The other packages
> implement predefined interfaces (already documented by Sun, for
> example), and add setExpected... and setup... methods, the names of
> which follow strict conventions and are derived from the method and
> parameter names defined by the API.
> 
> The steepest part of the learning curve, in my experience, was learning
> the naming conventions and how to apply the com.mockobject classes to
> the mocking of my own interfaces.  The source to the mocked API packages
> was useful guidance.
> 
> So, perhaps it would be better to write some tutorial documents,
> explaining the naming conventions and how to use the classes in
> com.mockobjects to create new mocks.  There already is a document on
> naming conventions, but it is quite terse and the link is tucked away in
> the corner of the mock objects home page.
> 
> Cheers,
> 	Nat. 
> 
> -- 
> Dr. Nathaniel Pryce, Technical Director, B13media Ltd.
> Studio 3a, 22-24 Highbury Grove, London N5 2EA, UK
> http://www.b13media.com
> 
> 
> 
> 
> -------------------------------------------------------
> 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
-- 
jeff martin
information technologist
mkodo limited

mobile: 44 (0) 78 5547 8331
phone: 44 (0) 20 2226 4545
email: je...@mk...

www.mkodo.com

RE: [MO-java-dev] Java Doc

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

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

Re: [MO-java-dev] Java Doc

[Ted H. <hu...@ap...>]

Vincent Massol wrote:

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

+1

For the next iteration of Struts, we'd like to base most of the 
documentation in  the "Developer Guides"  we've been publishing as 
package descriptions

http://jakarta.apache.org/struts/api/org/apache/struts/taglib/bean/package-summary.html#package_description

This way everything travels together and it's easier to keep it all in 
synch.

I'll look for an opportunity to starting putting something together for 
this project, but I like to do this sort of thing as I go and let it 
grow in the telling.

-Ted.