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:

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.

Rate

4 (2)

Share

Share

Rate

4 (2)