Mad Software

I have a confession to make. Forgive me. Wait, don't forgive me. I'm completely unapologetic. I am a programmer, and I don't write comments. I just needed to get that off my chest.

I don't believe in comments.

I have been writing a lot of fairly complex code lately. And all the while, the voices of dead Computer Science professors have been speaking to me. They repeat the mantra of good code commenting. I feel guilt, like when I go to church. Or when I don't make my bed in the morning. Of course, not one of them is able to give me any good suggestion of what a good set of comments is. They just tell me what isn't a good comment. So does that mean that anything else is a good comment? Like lots of swear words in the code. That's probably more useful than real comments, because they make me laugh and keep me from falling asleep at the keyboard.

Good comments, I'm told, are not just a rehash of what is already in the code. Well, if it isn't already in the code, then it isn't much use to the program is it? I don't believe in comments. I think they are mostly a waste of time. Maybe not for you, but for me they just make my life difficult. I have to make a context switch to English in order to write them. That takes time and just serves to confuse me.

Whenever I write English, I take the audience of my writing into account. Who is the audience for my comments? Some moron with a basic C++ book on his desk? Or the great man himself, Bjarne Stroustrup? Bjarne is pretty smart and will probably be able to figure out my code just fine without me, or my comments. Because he speaks C++. I speak C++ too, so that's how I like to communicate with computers and other people who speak the same language.

So I don't write comments. I'm one of those people who likes to use good variable names, good function names, and good file names. When I look at others' comments, I don't usually trust them, because they often don't make any sense. Or they are just plain wrong. That's just awesome. Like the time I first starting programming and I spent two days wondering why the second member of a pair of ints (pair) was always zero, even though the comments said it should contain some valuable piece of information. Actually, it was the first member, not the second one, which I finally figured out by actually looking at the damn code. Wonder of wonders, the code actually told me what the code did. Amazing.

I think that instead of comments we should put quotes of great authors at the top of all our code. That way, when people read our code, they will think that our code is profound, because we quote the greats of our time like, Dostoevsky, Helen Keller, or Dave Barry. And the best thing would be to just randomly pick those quotes so that when people try to make some connection between the code and the quote, they'll spend lots of time trying to figure out. Then they'll feel stupid, but won't want to admit it and we can fun of them when they can't explain the connection. And we won't have had to be smart at all, because all those people that we referred to are smart.

Have I even written comments? Of course, I slap all my comments in the headers, when I don't feel like writing documentation. Or when the function name is getting too long. Or when some fellow programmer makes me feel guilty for not following the religion of comments. What is the point of writing commments if the function name tells the whole story? Take vector for example, the size() function returns, guess what, the size of the vector. I know what you're thinking, that is completely non-intuitive. It's got to be commented. Look, if the function name can't tell you what the function does, then maybe you should change the function name. And if your function name gets too long, then maybe your function is doing too much.

Good, maintainable programs are easy to understand not because they have lots of comments explaining their complex structure, but because they are straightforward, not complex. Complex is a synonym for spaghetti. Code should be more like ravioli. Good ravioli, not that crap they give you in restaurants. Chef Boyardee is delicious. The mental model of a good program is easily understood by normal humans. And if that mental model is nice and straightforward, then the functions that act on it should also be straightforward. A function called get_ the_ thing_ and_ reroute_ the_ other_ thing_ with_ the_ thing_ you_ have_ from_ before() doesn't need to commented, it needs to be thrown out. The class it lives in probably does too. It's doing too much.

I'm religious, but not about programming. In religion, there are things that you believe just because they seem right. Code comments may feel right, but they just don't prove their value outside of giving people a good feeling. I'm going to love my enemy for no good reason, because that sounds like a good idea. But I'm not going to type any more comments until I have a mathematical proof that it's good for me, like ravioli.

Labels: programming