The Search For Self-Documenting Code

By Craig S. Kaplan

Historical Note:

This report has been getting a lot more attention recently as a result of it being discovered by Yahoo!. In light of that, I figured I would provide just a little context for it.

As a COOP student at the University of Waterloo, I was required to write no fewer than four work term reports over the course of six internships. This was the fourth. It's important to realize that the reports are graded almost exclusively for form rather than content. An English major is assigned to read the report for grammar, spelling and punctuation. As far as they're concerned, I could be writing about crabgrass. Knowing my intended audience, I made some concessions towards a reader without extensive programming experience by including, for example, a glossary.

What you're about to read was written circa 1994. I re-read it recently. The writing is pretty rough (the bar was low for work-term reports, a fact that I certainly didn't call into question) but the ideas are sound. Hope you enjoy it.

I'm not exactly sure why Yahoo! put this page under its "jokes and humour" category. I guess it's not funny ha ha, just funny peculiar...


[back] [up] [right]