Tom Pittman's WebLog

(or something like that)

2006 February 14 -- Better Software

A friend of mine sent me some back issues of a magazine titled Better Software. It seems to be mostly about managing software projects with special emphasis on testing. One article I thought particularly noteworthy, although it seems to collect into one place ideas running through several issues and by multiple authors. Normally I would link you to the original text on the internet -- except these folks don't put their good articles up to link to. There are two problems: first, they want a $225 membership fee to access that page at all, then (after I complained and they gave me a trial membership), the article is not in HTML. I am not in the habit of linking to PrettyDarnFoolish documents, mostly because it is a proprietary and private data format supported by only one vendor with a long history of persecuting -- ah, I mean prosecuting (same thing) -- software developers trying to port their data formats to other platforms. So you will have to be satisfied with a general link to the Better Software home page.

The really good insight author Brian Button brings to this article is that the best sample code for other people to look at as they try to use your program code, is the test programs you should be writing anyway. Good unit tests explore the limits of the software they are testing, and they must be kept up to date with code changes, while ad-hoc sample code in separate documentation tends to get out of date as the code is revised (and documentation is not). Nobody likes writing and maintaining documentation, but if the test code is simple and readable, separately maintained documentation is unnecessary.

His only problem is that very large programs have so many test programs that finding the piece of code you need to look at can become difficult. Button suggests maintaining a roadmap of test programs -- while admitting that this roadmap document suffers the same flaw as all separately maintained documentation. He hopes the tool vendors will eventually get around to solving that problem.

Me, I'm a tool-maker. There is an easy solution to the problem. Easy, that is, for a compiler-writer like myself: Just invent special syntax in the test programming language that designates where this item fits on the roadmap and what the summary line there should be. The compiler can insist on this syntax, so your (test) program won't compile without it, and then it can automatically build the roadmap from all the test programs. The compiler can't force you to put meaningful comments there, but at least the foolish or out-of-date remarks will be there staring you in the face when you add revisions to the test code.

There is more in the article that I won't (and probably shouldn't) repeat here, but the fundamental idea is simple: Keep the test code simple, name the test programs descriptively, and release it to the users to look at. I'm working on a couple projects destined for open-source release, and I plan to use this idea extensively.

Thank you Brian.