KeepJavaDocInLineWithTestsStory

Background to this story: I've just seen some javadoc for some code I didn't write. To understand how to use it, I'd prefer to check out the code that tests it, but its often difficult to find.

-- PaulS

interesting, another problem that doesn't arise with VisualAge. We really are getting spoiled.

PaulS isn't sure he agrees with SteveF here - if you import a 3rd party class library then you still need to rely on the accompanying javadoc to explain what it does

True, but VisualAge will still do all the cross-referencing. You can select a method imported from a class file and see who calls it. (I've just been doing some stuff with ForteForJava? and it's so frustrating not having a VisualAge image (pace KeithBraithwaite)

Issues:

• it means putting test stuff in the target code, even if it is just a comment. How will this be kept up to date when we refactor the tests?
• most sites work with a convention for unit testing based on related package and class names.

We have found JavaDoc? to be unecessary - and we put our effort into making our tests be the documentation for the code. Thus for any class you find in our model, there will always be a class called ModelClassTest? which we actively build tests that document the class. If you ca't look at the tests and understand the model, then we improve our tests. JavaDoc? is awkward to use and I would avoid it if at all possible. If you are in the framework business and have to ship something to customers, then maybe it makes sense? Although I would still prefer to have the tests that run and I could copy examples from. -- TimM

PaulS agrees with much the above (though he thinks JavaDoc? is not awkward to use rather it is awkward to write). The key point is whether one can always rely on ModelClassTest? to test ModelClass?. This seems fine at the lower granularity of tests, but I wonder whether they are also tests which cover ground somewhere between unit and fn - perhaps testing the interaction of a few classes MVC-style?