From: Sam Roberts Date: 2004-03-24T03:55:11+09:00 Subject: Re: Need some advice on PickAxe II Wrote jrb3@eidogen.com, on Wed, Mar 24, 2004 at 02:01:05AM +0900: > > Lothar Scholz wrote: > > > I'm not saying we don't need the API, it just bothers me when people > > believe that an API is an acceptable way to learn the library from the > > getgo. If the API is well documented enough to have decent tutorials in > > it then perhaps, but that is not what most of the API's I have seen > > possess, though I find java to suffer from this even worse then ruby. > > Oh, of course! Unit-test libraries > within the libraries themselves, as if in Extreme Programming fashion! > > This will document the API with examples, and gift us with more ways > to support ports (eg to JRuby or new hardware). In my experience with our test code, good test code makes hideous example code. For one thing, we do everything wrong in our test code, the way only somebody who really doesn't understand the API would, so that we know that when such a person uses our API, it will not explode. For the same reason, example code is not good test code. Testing the normal cases is almost a wast of time ("almost", you still have to do it), the bugs are in the oddball and negative cases, using the api the way the developer thought it should be used almost always works. Cheers, Sam -- Sam Roberts