Daniel Russel wrote:
I should add that we do, eventually, want good coverage of our API with example code. However, that coverage just has to be thorough enough so that any any usage can be figured out trivially, no so that any function can be called by cutting a pasting a particular line of code.
But of course. I'm certainly not suggesting that our unit tests be the only examples. Unit tests and examples are entirely different (we don't even distribute the unit tests for Modeller, for example).
It might be worth adding a examples directory at some point.
Of course we need an examples directory - there should be no need to even discuss that. But we don't have one yet. (Sure, there were some examples in Bret's initial IMP checkin, but they were clearly designed to be test cases, in which case I put them into the test suite, or they didn't work, in which case I removed them.) When our API is a little more stable, we can think about writing examples.
Personally, I would really like it if the examples were built and run as part of the test suite and their output checked, just so that we know they are always working.
I don't know if you've ever tried doing that before, but for anything other than really trivial examples, you can't really check the output beyond "did it crash". Look at the Modeller examples, for instance. A given model building example will give dramatically different results on different operating systems (even different compiler releases on the same OS) due to the ruggedness of the scoring function landscape and the limited floating point precision available.
Ben
--
http://salilab.org/~ben/
"It is a capital mistake to theorize before one has data."
- Sir Arthur Conan Doyle