Re: Tests, Documentation

[Sascha Brawer]

graydon hoare <address@hidden> wrote on Wed, 26 Nov 2003 22:40:18 -0500:

> [many proposals for testing]

IMHO, most proposals sound very convincing.


>>>     - tests can be added inline with a source file, or "right next
>>>       door" in a similarly-named class or package.
>
>I guess my point is I'd like to lower, as far as possible, the cost of
>writing such a class, and putting it inline with the classpath code
>lowers the cost further (no need to do a separate "cvs add", open a
>new file, copy the legal boilerplate, etc.)

I would't find inlined test code too desirable, for several reasons:

1. The source files would get more difficult to read.

2. It would make it difficult to check the tests against the Sun JDK (see
below).

3. If tests were part of the sources, the size of the compiled code would
grow. This may be a problem for those users of Classpath who care about
memory consumption.

4. An inlined test suite might make some compiler optimizations more
difficult, because all code paths are executed.

One could avoid some of these problems by conditional compilation (#if/
#endif), or trickeries with some other macro engine. Personally, I would
be strongly opposed to introducing macros into Classpath code (because I
find macros evil, maybe with the exception of Lisp). But I'm aware that
any Real Programmer will have a different opinion. It's probably a matter
of taste.

Isn't "similarly-named class or package" exactly what we have in Mauve?

The tests for the method javax.swing.
undo.AbstractUndoableEdit.getPresentationName are located in
gnu.testlet.javax.swing.undo.AbstractUndoableEdit.getPresentationName.
Verbosity rules :-)

>my gut feeling (I don't mean to be insulting or dismissive, just
>observing) is that few people -- and progressively fewer as time
>passes -- will have a use for mauve outside testing classpath.

While I'd agree, I wonder whether it isn't in our own interest to run our
tests on proprietary Java environments. Runnning our tests against non-
Classpath implementations may help validating the test suite. Especially
in the case of the Sun JDK, which could be considered the reference
implementation for the Java environment. 


>is 1.0 testing -- or rather, running on a non-reflect-able JVM --
>really an issue? I appreciate the air of openness and compatibility
>suggested here, but some aspects of introspection are pretty handy,
>and can help automate a lot.

Hm, I'm not sure: Is introspection really part of every Java environment
that is being used nowadays? How about the mobile/connected device/...
profiles? (I don't know whether we want to care about these at all).

In general, I'd agree that using JUnit seems like a good idea. The bridge
class that you've sent to mauve-discuss is probably exactly what is needed.

About integrating Mauve into the Classpath cvs repository, I wouldn't
care a lot. I assume that the copyright issues that Mark mentioned would
possibly be solvable by letting people assign copyright to the FSF. But
would we gain much from Mauve and Classpath being part of the same source
tree?

>test-writing has to be made to feel at least as
>engaging as code-writing, if it's to be successful.

I imagine that this will be hard: For most people (including myself),
it's so much more fun to write code that actually does something.

Maybe we should take turns in baking chocolate cakes? Once a month, a
fresh cake would be sent to the person who has contributed the largest
number of test cases. Please don't laugh, I mean it seriously.


> [Documentation style]
>exactly my point: I think the user should get a short education in 2d
>graphics programming when they look up Graphics2D, not a list of
>method-by-method details. I'm happy to write the former, less so the
>latter.

Hm, this may well be a question of personal preference.

Personally, I'd like to have both good per-package introductions and
decent detail documentation. I think they serve a different purpose, but
both are equally important.

But we obviously have only limited resources. With my complaint, I mostly
wanted to whine about the piles of Classpath code that have no
documentation whatsoever.

In any case, I really don't think that "read the source, gal/dude" is an
appropriate answer to people who want to just use our code. It takes so
much less time to read a well-written description than to browse through
thousands of lines of code. (Again, others might well have different
experiences).

-- Sascha

Sascha Brawer, address@hidden, http://www.dandelis.ch/people/brawer/