[Biojava-dev] developers should use unit tests and watch for javadoc errors

[mark.schreiber at novartis.com]

Hi all -

There are quite a few new developers with CVS accounts so I would like to 
draw your attention to Unit testing.

BioJava uses JUnit Tests and has ant tasks for these (runtests for 
example). To enable this you pretty much only need to put the JUnit jar 
into your ant lib directory. Then from the biojava root type ant runtests.

I just did a CVS download and build after a few weeks break and found a 
few of the tests no longer passed. Changes had been made to the source 
code which compiled and presumably solved some problem but along the way 
had introduced subtle errors that caused the unit tests to fail. A 
particularly subtle one was a change that caused the compareTo() method to 
fail. You are not likely to notice this until you come to sort something 
and even then you may not pick it up.

If you make changes to the source code please run the Unit tests. Often 
changes in other parts of the code may affect the behaivour of methods you 
haven't touched (such as the compareTo example above).

I would also make a plea for people to contribute more Unit tests. The 
coverage is patchy and the more we have the more biojava will be bug free 
which means more of your programs will be bug free. If you use a certain 
class a lot and the Unit tests for it don't exist or are inadequate it 
would be a good idea to make or improve one so you can be sure of good 
behaivour. The unit tests for the biojavax objects are probably the best 
examples we have. They try to test every method, including the often 
neglected but very important compareTo(), equals(), hashCode() and 
toString(). They also try to test the behaivour described in the javadocs 
of the methods. If you want to write a Unit test take one of these as a 
template.

Finally a word about javadocs. One the whole the number and quality of 
javadocs has vastly improved over the last year. If you add or modify 
javadocs run the ant javadoc-biojava task and check for warnings. This 
allows you to avoid common errors such as misspelled @param names or @see 
tags that can't locate the class you want to reference. It's a good check 
if you have been copying and pasting javadoc comments.

In conclusion some basic guidelines for developers:

* New classes should have full javadocs and a JUnit test (inlcuding equals 
etc).
* New methods should have javadocs (not required if it is a private 
method) and add a test of the method to the JUnit test.
* Before any commit run the JUnit tests to make sure you haven't broken 
anything and run the javadoc task to make sure your @params etc are all 
correct.

If you observe this behaivour biojava will be a lot more stable and better 
documented which will give us a better reputation and mean that your code 
works more often.

Sorry for the sermon.

- Mark


Mark Schreiber
Research Investigator (Bioinformatics)

Novartis Institute for Tropical Diseases (NITD)
10 Biopolis Road
#05-01 Chromos
Singapore 138670
www.nitd.novartis.com

phone +65 6722 2973
fax  +65 6722 2910