Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 

Worst Practice - Bad Comments

By Andy Warren,

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.

Total article views: 9404 | Views in the last 30 days: 3
 
Related Articles
FORUM

Worst Practice - Bad Comments

Comments posted to this topic are about the content posted at http://www.sqlservercentral.com/column...

ARTICLE

Worst Practice - Bad Connection Strings and Bad Info in Sysprocesses

Andy returns to the Worst Practice series this week with a short article looking at how connection s...

FORUM

Nested Transactions - Best Practice

Nested Transactions - Best Practice

FORUM

Database backups best practice

Database backups best practice

BLOG

Commenting TSQL Scripts

If you have ever searched for “commenting in TSQL” scripts, I am sure that you’ve found hundreds or ...

 
Contribute

Join the most active online SQL Server Community

SQL knowledge, delivered daily, free:

Email address:  

You make SSC a better place

As a member of SQLServerCentral, you get free access to loads of fresh content: thousands of articles and SQL scripts, a library of free eBooks, a weekly database news roundup, a great Q & A platform… And it’s our huge, buzzing community of SQL Server Professionals that makes it such a success.

Join us!

Steve Jones
Editor, SQLServerCentral.com

Already a member? Jump in:

Email address:   Password:   Remember me: Forgotten your password?
Steve Jones