There be dragons here

Caution: There be dragons here
Programmers' caveat

It's been forever since I posted anything. I've mostly been at a loss of what to post, mainly because my job has gotten interesting again, and I've been somewhat engrossed by what I'm working on. It's a new web development project using ASP.NET 2.0, SQL Server 2005, and VS 2005 (those who care will know what that all means). Anyway, I figure if that's what's on my mind, that's what I should blog about. So, a few thoughts and observations on comments....

Comments are bits of text in a program that are ignored by the computer. They are there for the sole benefit of other developers who may need to look at your code (not to mention your own benefit, should you need to remember what the hell it was that you did five months ago). They're akin to footnotes in a book, explaining the stuff that may not be obvious to the reader. Good comments are a hallmark of good programming.

Notice I said "good" comments and not "abundant" or "copious" or "numerous" comments. That is because comments, like food, is best in moderation. Not enough, and your program becomes an incoherent shell. Too many, and it becomes a bloated mess. Good programmers try to write programs that other good programmers can follow. Yet sometimes it is necessary to provide a some additional clues as to why your, say, multiplying that number by 3600 (it's in seconds - you want hours). Okay, programmers our there are right now saying, "You don't need to comment that! Any fool could figure that out." You're right, bad example, but you get my point.

Most of the time, one line is all you need. "Make sure the number is not zero," for example. Every now and then, though, you need to do something in your code that's a lot more complex and potentially confusing. Maybe five lines are needed. Then, there's the odd occaison when even you are disconcerted by the confusing nature of what you have just written. Yet, you cannot find a simpler way of doing it. There are many reasons why this may be the case. Often the vendor tools you're using have boxed you into the corner, and this obtuse mess you've just created is the only way out.

When in such situations, you often find developers leaving the comment:

Warning: There be dragons here.

Sometimes, they'll go so far as to say, "serious dragons." Generally this is to be taken, "Read the following code very carefully, or you might screw things up royally." After this comes a detailed explanation if what's going on. Often, there is also some justification of why it had to be done this way. It's an admission that the code is aweful, as in, "I'm really sorry you have to deal with this crap. Truly I am. But if you were in my shoes, you'd have done the same thing and you know it."

I'm writing all this because I'm coming close to the "dragons here" threshold. I am expanding and enhancing an existing tool, so I can claim that, in large part, it's not my fault. I've also found myself cursing the tool's original authors who, IMHO, did not practice good commenting. Some of the code comes close to what I like to call, "Heart of Darkness" code. This is code that is so bad that, when you finally make you're way through it to the other side, you're left muttering, "the horror.... the horror."

It is not the worst code I've dealt with, though. The worst code was very early on in my carreer. I had to find a bug in an X-windows application call xterm. When I openned the first source file, I found this comment:

WARNING: This code particularly, the tty setup code) is a historical relic and should not be confused with a real toolkit application or a an example of how to do anything. It really needs a rewrite. Badly.

And let me tell you, the author wasn't kidding. But at least they had the honesty of saying so up front. I printed this comment out and hung it on my wall.