Jeremy Hylton : weblog : 2003-10-09

Better Blogging

Thursday, October 09, 2003, 11:53 a.m.

I'd like to write more shorter entries for the weblog. Two events conspired to get me on that track today. I fixed my weblog generator to deal with multiple entries on the same date, and I read Coding Smart: People vs. Tools by Donn M. Seeley.

Fred Drake pointed out that my RSS feed had an item about pychecker that pointed to the Johnny Apple item. I hadn't tested the generator when I wrote two entries for that day, and it sort of looked like it worked. It had generated a decent looking front page by accident, but that was it. So I fixed the software to use individual letters as tags in addition to the date.

Seeley's article, in ACM Queue, has a list of good work practices. First on the list is 1. Keep full development notes and debugging logs:

I use lab notes extensively. Now that this practice is ingrained, I can't imagine how I survived before. My notes are all online so I can search them using pattern-matching tools, and because I type faster than I can write. This practice gave me the single biggest boost to my productivity, reducing the amount of time spent trying to remember what I did a year ago/a month ago/a week ago/yesterday. Always record your breakthroughs and dead ends so you won't have to reinvent them. Lab notes are an amazing productivity tool that many good programmers never use.

Closely related to lab notes is the debugging log. You can keep track of debugging notes in a variety of ways: Annotate your debugging experience by hand; cut and paste debugging material into a lab-notes file; run a line-oriented debugger inside a scripting environment; or do all three! With logs, you should never need to re-create a debugging situation just to see the same data, and you should be able to search the logs for particular names or values later.

I've never used lab notebooks extensively. I use tools that produce some long-term records, like a version control systems, and I try to keep a lot of my email. Over the last few years working with Tim Peters, I've also started putting important hints in comments in the code. Comments and revision history are useful in a narrow way, because they are tightly integrated with my programming tools. Email is less useful, because it's hard to manage and search email.

A web log can serve as a useful notebook. It will get indexed by Google, so there's a decent search mechanism. I already use Google to search other people's "debugging logs." If you get an obscure error message you don't understand, just search for it with Google. If you're lucky, you'll find mailing lists where people asked and answered your question; it's so unlikely you're the first person to ask. If you're unlucky, you'll get a checkin message with the code containing the error text.

A tangent: I've enjoyed reading ACM Queue. It's too bad I can't get it instead of Communications of the ACM with my ACM membership. CACM seems to be overtaken by management professors; I seldom read anything other than Beyond Risks.