I wasn't burned at the stake for my CruiseControl article. Slightly singed is all. Obviously I need to try harder. (By the way, thank you for your comments. I've been busy reviewing papers for the Agile 2005 conference, but I still intend to reply.)

Well, nothing should get me roasted better than baiting Slashdotters. (Yes, I admit it. I read Slashdot. But I only read it for the articles.) Recently, they posted an article about comments being more important than code.

In response, I'll dust off an ancient example of non-commented code. I wrote that (in 2000 or 2001, I think--back before I got married and changed my name, anyway) in response to a challenge that some code simply has to be commented. My code only has one comment, and I still think it's better documented than the original. See for yourself.

Remember, the tests are part of the documentation, too! In fact, the tests should tell you everything you need to know in order to use the class, leaving reading the code itself--and its one comment--as an exercise for the curious.

Here's an excerpt from the tests in case you don't feel like clicking the link. It's written in Java.

public class _TestQueryStringParser {
...
  public void testOneNameValuePair() throws IOException {
    _expected.put("name", "value");
    assertEquals(_expected, doTest("name=value"));
  }

  public void testMultipleNameValuePairs() throws IOException {
    _expected.put("name1", "value1");
    _expected.put("name2", "value2");
    _expected.put("name3", "value3");
    assertEquals(_expected, doTest("name1=value1&name2=value2&name3=value3"));
  }
...
}

I particularly like how well documented the edge cases are. Questions about behavior are what make you read code in the first place, and these sorts of obscure questions almost never answered with comments, no matter how good they are. These tests show exactly what's going on.

  public void testRealSpace() throws IOException {
    _expected.put("name 1", "value 1");
    assertEquals(_expected, doTest("name 1=value 1"));
  }
...
  public void testDegenerate_TwoNoNamePairs() throws IOException {
    _expected.put("", "value1b");
    assertEquals(_expected, doTest("=value1a&=value1b"));
  }