A look at comments
17October 21, 2013 by Kenneth Fisher
Everyone knows that we should include comments in our code right? On the other hand the vast majority of us don’t use them as much as we should, myself included. Believe it or not I actually got a job based on the comments I had put into the tech test. It was between me and another person, both of us finished the tech test in about the same amount of time, with code that was similar enough to make for a difficult decision between us. However, I had carefully commented my code (for my own use more than anything) and I ended up with the job. And in case anyone is wondering how I know it was the comments that got me the job, the manager told me after I had been there for a while. On that note here is a brief look at comments in T-SQL.
Here is some common knowledge about comments
--This is a single line comment PRINT 'This is an example ' -- of commenting part of a line -- This is -- An example -- Of commenting -- Out a block -- Of code
/*This is a single line comment*/ PRINT 'This is an example ' /* of commenting part of a line*/ /* This is An example Of commenting Out a block Of code */
Not as common knowledge about comments
This works
/* /* */ */
This does not
/* /* */
This works
-- /* PRINT 'Playing' PRINT 'with' /* PRINT 'block' PRINT 'comments' */
This does not
/* PRINT 'Playing' PRINT 'with' --/* PRINT 'block' PRINT 'comments' */
Some common comment usages
DECLARE @EmplrName varchar(50)-- Employer Name DECLARE @Status varchar(10) -- Hold, Ready, Complete
----------------------------------------------------- -- Declare and initialize variables Code here ----------------------------------------------------- -- Process order information Code here
----------------------------------------------------- --=================================================== --*************************************************** /***************************************************/
A couple of comment lines, maybe with a descriptive comment in the middle, can provide extra emphasis to a section of code.
--=================================================== --=========== Load and process employees ============ --===================================================
-- This is a loop WHILE 1=1 BEGIN -- This is what the loop does PRINT 1 END
/************************************************************* ** This stored procedure is really important. It does stuff ** Parameter list ** @StuffToDo -- What do you want the stored procedure to do ** @WhenToDoIt -- When do you want it done ************************************************************** ** 10/20/2000 - Fixed bug that made nothing happen. ** 11/21/2001 - Put bug back in because to much was happening. *************************************************************/
SQL Studies 
Nice overview on comments. I often use the ctrl+kk to set a placeholder in my query when I am bouncing about between scripts so I know where I left off. This is especially helpful when you have a lot of queries in one window and you step away and then come back. Otherwise, you might have query results but have forgotten which query they came from!
Thanks. I’ve never tried ctrl-kk before. I’ll have to give it a shot.
I often use a –/* to open a section of T-SQL and leave a –*/ at the end of the section. Then removing the inital — from the opening section comment will comment out the entire section regardless of how long the code section runs/ This saves a lot of scrolling to the “bottom” when trying to enable/disable code sections during development and test.
That should read as ‘dash-dash-stroke-star’ and ‘dash-dash-star-stroke’.
Not a bad idea. I’ll have to give that a shot some time.
Nice basic info. I found this article to be helpful – http://www.sqlservercentral.com/articles/T-SQL/100061/
You’re right, that’s a good article. Thanks for the comment!
[…] on schemas, tables or columns. Comments on SPs, functions etc are common and easy enough to do. They can let you know what changes have been made and why, what […]
I require that our developers & DBAs include the author & create date of the stored proc in the top section you’ve set aside for parameters & changes. I do include the asterisks lines though. 🙂
Absolutely! It’s great to be able to go back to the original author & ask questions. Of course it’s also fun to be able to look at something several years old and say “Hey, do you remember when such and such worked here?” 🙂 (We have a lot of REALLY old code)
Comment on your post on comments:
You said: •If you highlight a section of code and hit ctrl-k, ctrl-u then SSMS will automatically un-comment (remove the double dash) every line that is even partially highlighted.
Removing a double dash is not always synonymous with uncommenting. If you have four or more dashes, ctrl-k, ctrl-u will still leave the line commented.
I use this technique a lot in demo scripts, where I have a section that is to be run in another connection, but I want that other section to have its own comments. Like this:
——————————————————–
— — Run the following in another connection:
— — This code will acquire a table lock
— BEGIN TRAN
— UPDATE t1 SET c1 = 0
— — Do NOT commit this transaction at this point
— — etc ……
———————————————————–
So everything between the lines of dashes is copied (ctrl-c) and pasted (ctrl-v) into another SSMS window, and then in that window, I select it all (ctrl-a) and then uncomment with ctrl-k, ctrl-u. There will still be comments left in this code.
When I was a university instructor, comments definitely made a difference in the grades I gave my students.
Thanks for a great post!
~Kalen
Great point! I should have mentioned that. Did you know you can use alt+(mouse or shift) to highlight a block and run or copy out a section that doesn’t include the -‘s?
Thanks for the great comment! 🙂
[…] the last effort, so I’m having a hard time understanding some of it. I needed to put in more comments. And that’s what I could find. In a bunch of cases I know I saved something I need now but I […]
[…] actually going on, and as you learn to tune it out, you are also learning to tune out the real comments. And comments are […]
[…] talked about SQL Server comments before and how important they are. In PowerShell comments are important for all the same reasons […]
[…] a big fan of comments (MSSQL, Powershell), so along those lines here’s an interesting way to comment an IF-THEN-ELSE […]
[…] code with what was happening in each section, what different variables are for, etc. You know .. basic commenting. But since I was creating a piece of code for someone else to run I put comments inside the […]