Worst Practice - Bad Comments

Steve Jones & I have been writing for a while about Worst Practices for a while, our attempt to spark some thought and conversation about things that are just plain wrong! At least according to us, your mileage may vary. So let's talk about worst practices in commenting your TSQL (and to a large extent, any other code you write).

Here's an example of the 'flowerbox' style, where the author uses hyphens, asterisks, or some other character to box in the comment to make it...just so:

The problem becomes when you want to modify the comment. You have to spend time adding or subtracting spaces, otherwise you end up with something like this:

Does it matter if they line up or not? Not really. Yet they leave a sense of code half done, that the author just didn't care enough to neaten things up. Neatness isn't just there because we're supposed to put our dirty socks in the hamper, neatness contributes to readability and that IS important. 

Now just me, but I think the borders serve no purpose. I like to keep the proc concise, why introduce scrolling if you don't have to? If you're going to do a border, just omit the left and right portions as shown next, that way you can change your comments at any time without destroying the look.

Another horrible commenting trick is to leave old code in place. In this example, we have a poorly done select, someone has done the right thing, explicitly selecting the needed columns and supplying the table owner to make the proc more efficient. But they've left the old code behind. Why? Usually it's because they want to keep the old code while they test the new. No problem with that. But once it works, what purpose does it serve? The most popular response is that "we might need it again sometime". Fine. Two ways to solve that. The standard way is to keep the proc under version control, you have all the history you need. The other is to actually create a new proc (see my Version Control article). Either way, delete the old code!

I guess you could call not commenting a worst practice. Or is the code self documenting to the point that comments are superfluous?! I'd be interested in hearing if anyone has reasons for not commenting.

Finally, there is the idea of useless comments. I'm not really in favor of the big headers that have name, date, what change, etc, though maybe I'm in the minority? Does not stamping the proc with that stuff everything count as bad? I don't think so, but maybe you can convince me!

Even if you convince me that headers are good, here is a truly useless comment example:

Don't tell me you haven't seen them! That comment does absolutely nothing to help me understand what the code does, and that's why we comment! Leave out the comment, tell me why I only need col1 and col2, or why I'm using table1, something that adds value that can't be expressed in code.

Have you seen other commenting worst practices? Agree with the ones listed? Had any luck stopping them in your organization? If you've made it this far I hope you'll take another minute to rate the article and add a comment. Reader comments really round an article.