& 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:
| create proc usp_TestComment1 as /* ----------------------------------------------------------------------- - This proc is just to show you how not to do comments. - ----------------------------------------------------------------------- */ |
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:
| create proc usp_TestComment1 as /* ----------------------------------------------------------------------- - This proc is just to show you how not to do comments. I just changed it - ----------------------------------------------------------------------- */ |
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.
| create proc usp_TestComment1 as /* ----------------------------------------------------------------------- This proc is just to show you how not to do comments. ----------------------------------------------------------------------- */ |
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!
| create proc usp_TestComment1 as /* ----------------------------------------------------------------------- - This proc is just to show you how not to do comments. - ----------------------------------------------------------------------- */ --select * from table1 select col1, col2 from dbo.table1 |
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:
| --select columns from table1 select col1, col2 from dbo.table1 |
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.
