squelch the sigmangler.

I had to read someone else's code today. It wasn't too bad, because there was a healthy smattering of comments thrown in. If you already know about comments, please feel free to skip the following section.

Some smart programmer long ago decided that it would be nice if people could put regular text into code. Something that a person could read, but that a computer would know to ignore. These are comments. They were a Good Idea.

Even for those of us who know how to read code, reading English words (or Dutch or Swahili) is still pretty much easier. And so rather than have to read a piece of code, you'd rather read some text that just tells you what it does. At that point, you can decide to trust that the code does what the comment says it does and skip reading it. The code may not actually do what the comment says it does, but it at least usually states what the author meant for it to do. It's the thought that counts.

So instead of having to figure out this:
int product = 0;
for (int i = 1; i <= 100; i++) {
     product *= i;

you can just look at this:
// finds the product of all the numbers from 1 to 100, dummy

It's not as big a deal when you're only writing programs that find 100!, but unfortunately, I usually have to write stuff more complicated than that. Sometimes I have to find 200!.

Some people do not put comments on their code. When I was a young, naive college student, I didn't use comments very much. But that was because I could turn in an assignment after two weeks and never look at it again. But now I have to come back to code that I wrote last year, and I don't remember what it did. I write comments for the mental health of my future self. Oh, and also any colleagues that might have to look at my work. But mostly just for my future self.

I find that my personality starts to show in my code through the comments. Sure, I recognize bits of me in the code itself, but that's more recognizing my coding style. The comments show the regular me that has nothing to do with programming. I can hear my own voice saying the words. You can see a programmer's mood through the comments. Whether they are feeling frustrated, fatigued, or smug about their code, it will come through.

I find that a few goofy comments will keep me sane. They're sort of fun to write, but then they're really fun to find again. So if I have to come back to some code that I wrote and then forgot all about, an amusing comment will cheer me up. It also completely wrecks my train of thought, but usually it's worth it.

I've been looking through some other code today, and I've found evidence that there are others in this world who feel the way that I do about comments. These are all from the Perl debugger. I don't know what all of them mean, but I feel a connection to the programmer who wrote each and every one of them.

# squelch the sigmangler
# Why -1? But it works! :-(
# Old stupid way...
# O Happy Day!
# Alas, poor unfortunates
# I just *know* there are men without -M
# Just exactly what part of the word "CORE::" don't you understand?
# mysteriously vaporized
# Here begin the unreadable code. It needs fixing.

And just for my own amusement, here is a comment I wrote. I try not to laugh too loudly to myself since I work in a cube farm, but I simply couldn't help myself.

// create our search hash...mmm, search hash


Anonymous said...

Oh. My. Gosh. You are so funny. And you and Sid are so much alike. I have always thought that, but now I have incontrovertible proof (did I use that long word correctly?)

I have always told Sid that he is his own favorite comedian, that he is the best entertainer of self and enjoys his own jokes more than anybody I have ever seen.


Sandra said...

Sid is my second favorite comedian.