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

[Richard Holland]

Hello all.

In addition to this, be careful with Java versions. BioJava is written
for Java 1.4. All binaries in CVS have been compiled with 1.4. BioJava
will compile successfully under 1.5 with a few extra warnings, but you
should not check any 1.5-compiled binaries back into CVS as then others
may not be able to use them.

Note also that the current version of JUnit (4.1) was compiled with 1.5.
If you want to run JUnit against BioJava using 1.4, you have to find and
download JUnit 3.8.1, which was the last release of JUnit to be compiled
with 1.4.

cheers,
Richard

On Tue, 2006-07-04 at 10:43 +0800, mark.schreiber at novartis.com wrote:
> 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
> 
> _______________________________________________
> biojava-dev mailing list
> biojava-dev at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/biojava-dev
-- 
Richard Holland (BioMart Team)
EMBL-EBI
Wellcome Trust Genome Campus
Hinxton
Cambridge CB10 1SD
UNITED KINGDOM
Tel: +44-(0)1223-494416