Literate testing

The notion of Literate Programming has been around for a while, but I’ve never seen it used in real life. The concept is very simple: put your code and documentation in the same file. “Documentation” in this sense, is not comments, but something more akin to Javadoc. When you comment your code, you’re basically adding comments to a source code file. In literate programming, you add your code to a document file. One example of a literate programming tool that I’m aware of is LEO .

Proponents of unit tests, including me, say that the unit tests provide good documentation for a class. They tell you how to use the class, and come with a built-in guarantee that it runs as advertised (assuming you run your tests regularly). This can be effective, if the unit tests are easy to find (like in a file right next to the class).

Philip Eby wrote an article about his eureka! moment with the Python doctest module. Intriguingly, what Philip writes about could be described as “Literate Testing”. Since unit tests already help perform a documentation function, actually building up a more descriptive document around your tests seems like a good idea. It’s a way to describe some of the rationale behind the code, instead of just describing how you use it. It also provides a chance to describe (possibly including more tests) how the class fits into the big picture of the overall system.

Any text documentation can certainly get out of date, whether it’s javadoc or docs that flow along with the tests. I like the idea of putting the docs with the tests, rather than with the code, because the part of the development where you’re writing the test is where you’re thinking at a higher-level about what you’re going to do. When you get into the code, you’re down to thinking about how you’re going to implement the feature. Javadoc is not quite ideal for this, but agiledox (testdox) could be pushed in this direction.

Python’s doctest module lets you put the tests right into a documentation string that appears either in your main source file or in a separate test file. Philip likes the idea of putting the docs and tests in a file separate from the code, and I do, too. I think it makes the flow of reading the docs/tests and the flow of reading the code a lot more pleasant.

The recent disgruntled rumblings in the Java community about JUnit and its lack of evolution have led people to think of alternatives, like TestNG. One interesting alternative to consider is doctest. Since Jython can import Java classes, there’s no reason that you couldn’t interactively test a Java class and write a file containing doctest-compatible tests that exercise your Java classes.

Selling software with eSellerate

The other day, Tim Bray pointed to eSellerate, a company that provides software download fulfillment services. Sounds like Tim had a good experience as a purchaser using their service. The cost is 10-15% of your revenue, which is pretty steep when compared to doing your own credit card processing (2-4% + some fixed fees, depending on which cards you accept, etc.). However, eSellerate handles everything for you and it sounds like they do it well. Seems like a nice thing to outsource, if you ask me.

Making rich webapps actual webapps

I was going to write a follow-up to Scott Delap’s rich webapp rant, but it turns out that Frank Carver has already written it. There are a number of things that creating a webapp gives you “for free”: back/forward, printing (of everything), bookmarks, URL cut/paste, reload/stop, etc. People like these features. In fact, the Swing app I’ve been working incorporates a few of these features, because they represent a minimum set of functionality that people have come to expect.

Frank makes great points, though. There are good reasons to create rich webapps. If you do, make sure that the thing still behaves like a webapp. It’s good to remember things like bookmarks, while making a webapp that reduces “server round-trips”. For example, in gmail, maybe I’d like a bookmark to a conversation… as far as I can tell, I can’t do that. (Why would I want a bookmark to a conversation with such great search features? Beats me… so, maybe it’s a trumped up use case.)

Even if the gmail example is not valid, I’m sure there are plenty that are. Imagine a customer relationship management app. If a salesperson is working with one particular customer a lot, they may wish to bookmark the main contacts page for that customer for quick access. That seems like a good feature to have, and it’s one the browser gives you for free, if you don’t try to work around its standard mechanisms.

John Gruber: Ronco Spray-On Usability

I’m going to be blogging some of the great articles that appeared in Joel’s nominations for best of 2004. Daring Fireball: Ronco Spray-On Usability by John Gruber is one such article. The gist of the article is that usability is, in fact, important work and not something to toss in as an afterthought. He picks on Eric Raymond’s article on Linux usability. I’ve read ESR’s article and it was interesting, but I think that Gruber is spot on when it comes to the real problem and the basic lack of a solution. I’ve had a really hard time figuring out who would actually use Yellow Dog Linux. Why would you want to replace Mac OS X, which is Unix with a solid, consistent GUI, with Linux and all of the stuff that entails?

Be sure to also read the followup.

Rich web applications

Rich web apps are all the rage these days (at least for those folks who are not trying to revive Swing on the desktop), and with good reason. Modern browsers, even the comparatively broken IE, have enough standards support to reasonable program sophisticated interaction. From Joel On Software’s Best Articles of 2004, comes this nominee: Koranteng’s Toli: On rich web applications, AlphaBlox and Oddpost. This article talks about the large amounts of JavaScript hacking that went into creating usable spreadsheets and presentation programs that run in the browser.

When asked how mere mortals (ie people who don’t have a whole team doing JavaScript for a year) can get in on the rich web app game, Koranteng Ofosu-Amaah suggested netWindows, which does sound interesting indeed. netWindows has a date picker, “content area”, split pane, sortable table, tree, menu and more… all supported in modern browsers, released under a liberal license. Most importantly, support is baked in for transferring data to/from the server without a refresh. As anyone who’s used gmail knows, this is a pretty key thing to making a responsive webapp.

I haven’t used netWindows yet, but I will definitely be taking a look at it later.

Comments are broken

Thanks to alert reader Andreas, I have discovered that comments on my blog are broken right now. I’m looking into it.

There appears to be some problem with SCode, the MT plugin that produces captchas for the comments. I’m not willing to turn off SCode, because I had too much cleanup to do due to comment spam.

My new company name is NOT…

Normally, companies announce events, as in something actually happening. In today’s age of blogging, I decided that I’ll go ahead and announce that the name of my new company will not be Zesty Software. This is literally a non-event.

For a while now, I had been thinking of using the Zesty name. I’ve been pretty sure all along that would be taken. That’s a strike against, for sure, but not a deal-breaker. Sure enough, is owned by a “Zesty International”. Who knows what they do, though, because they haven’t actually put anything at

The deal-breaker came when I did a Google search for “zesty software”. There were no matches, so it looks like the name was not in use. But, a few matches down I saw a reference to spyware that apparently opens up people’s browsers to a site called ZestyFind (no link provided, because I don’t want to support those who support spyware). I don’t know how common the ZestyFind spyware is, but I don’t want to be associated with that.

Back to the naming drawing board, I guess.

Art tips for programmers

In a couple of weeks, I’ll be starting in on my new business. In addition to being a businessman, I’m a programmer. (Of course, I’m also the janitor for my new business 🙂 One thing I’m not is an artist.

Making a modern piece of software requires at least decent taste, if not the actual ability to make good, appropriate visuals from scratch. The 80×24 text mode days are long gone. Luckily, there’s Slashdot to the rescue with Art Tips For Programmers?. The discussion thread includes all of the usually /. nonsense (I call BS!). It also includes a number of useful tips and links… like: use students from your local university, but don’t abuse them. And don’t count on them to finish on time. Or, just use professionals, because they’re worth the money. Surprisingly, no one said “outsource the graphics work to Russia”. Like any /. thread, there are plenty of opinions and options, and I’ll have to figure out the right one to use in a couple of months.

In the meantime, though, I wanted to keep track of some of the handy links that appeared in the discussion.

  • KDE-Look has icon collections, many of which are LGPL or other useful license
  • InterfaceLIFT has collections of stock icons
  • Not surprisingly, so does
  • Aquatint gives any image that friendly Mac Aqua glow
  • The Color Scheme Generator is a web-based doodad that provides assistance for folks who don’t have a good sense of color coordination.
  • If stock photos is your thing (and I’m not sure that it’s mine…), stock.xchng provides free stock photos. I wonder how dilligent they are about copyright clearance? Even if they aren’t, it would probably be unlikely that someone would notice.
  • Microsoft provides a detailed guide for creating Win XP icons. This includes colors to use, angles of images, sizes, etc.
  • A couple of people raved about Drawing With The Right Side Of Your Brain. While I will certainly admit that the “after” pictures in the gallery are technically far superior to the before pictures, they all look rather grim and scary. Still, if you’re looking to pick up drawing yourself, it would appear that this will help you with light and dark rendering and picking up detail in images.

Update: At least 100 of you probably saw the crazy initial posting. I fixed the odd cut and paste thing that had happened. Also, Chris Sterritt writes in:

For whatever it’s worth, the book is named “Drawing On The Right Side Of The Brain”. It was a book before it was a website :-). I kind of agree about the images on the website (they seem to all overemphasize the lines around the eyes)… the ones in the book are more appealing.