Years ago when I was a developer at Microsoft I found myself debugging deep in the bowels of GDI, the part of Windows that actually draws windows on the screen. Around the same time I had decided that come hell or high water I was going to make it all the way through Ulysses, and found the two activities oddly reminiscent of one another. For the more challenging sections of Joyce’s novel I found it helpful to give up actually trying to understand what was going on in any conventional sense, but rather just slogged along sentence by sentence, as if English were not my native language. Likewise, I didn’t debug GDI so much as step blindly through, grasping local bits of logic here and there while remaining in the dark about how they all came together. At one point I found myself in the middle of a long function where several strands seemed to converge, when from out of nowhere there appeared the following comment:
You connect the dots. You pick up the pieces.
This is a line from the Laurie Anderson song “Sharkey’s Night” where these words are spoken by the novelist William S. Burroughs in his inimitable frog-demon deadpan. The reference was so completely unexpected, yet technically apposite, that I laughed out loud.
This is the only time in history that a source code comment has been amusing. Every other attempt has been and will be infuriating. Always and forever.
Computer programmers of the world: you are not funny. Don’t try to be. This is good advice for life in general, but goes double for comments in source code. Perky exhortations to pay attention grow more enervating with each exclamation point. References to African versus European swallows are actually dorkier when rendered by Javadoc. And when I’m still at work at nine in the evening slogging through your buggy code, a sarcastic aside about how you know it’s full of bugs is in no way charming.
When you write a program you are writing for another person. The audience for your source code is as much another developer as the compiler, because otherwise why not just slap down a bunch of 1s and 0s? Obviously the human-readable comments are for human consumption as well. Obviously but also–seriously. There is a real living, breathing person on the other end of everything you write, and their time is valuable, so you owe them the courtesy of demonstrating that you are not merely amusing yourself.