A look at comments

12

October 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

  • In SQL Server to comment a single line (or part of a line) you can use a double dash.
  • --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
     
  • And to comment a block of code you use /* to start and */ to finish the block.
  • /*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

  • If you highlight a section of code and hit ctrl-k, ctrl-c then SSMS will automatically put a double dash in front of every line that is even partially highlighted, effectively block commenting the section.
  • 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.
  • Note: For the above two “tricks” the double dash goes at the front of the line even if you only have part of it highlighted.
  • A comment block has to be closed even if it is inside of another comment block.
  • This works

    /*   /* */   */

    This does not

    /*   /*   */
  • /* can be commented out outside of a block comment but not inside of one.
  • 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

  • Comments right after a declared variable can help define what an abbreviation is or what values should be used.
    DECLARE @EmplrName varchar(50)-- Employer Name
    DECLARE @Status varchar(10) -- Hold, Ready, Complete 
  • A comment “line” can be used to divide sections of code. This is particularly helpful if you include an actual comment to define the section.
  •  -----------------------------------------------------
    -- Declare and initialize variables
    Code here
    -----------------------------------------------------
    -- Process order information
    Code here
  • Not all lines need to be all dashs. Play with other characters to see what you prefer.
  •  -----------------------------------------------------
    --===================================================
    --***************************************************
    /***************************************************/

    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 ============
    --===================================================
  • Formatting your comments with your code is much easier to read and makes it clearer which line or section of code you are describing in your comment.
  • -- This is a loop
    WHILE 1=1
    BEGIN
    	-- This is what the loop does
    	PRINT 1
    END
  • A comment block at the top of a stored procedure is a good place for a general description of the SP, comments about the parameters, and over time what changes were made and when.
  • /*************************************************************
    ** 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.
    *************************************************************/

    12 thoughts on “A look at comments

    1. Ken says:

      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!

    2. jkeefe says:

      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.

    3. Dave says:

      Nice basic info. I found this article to be helpful – http://www.sqlservercentral.com/articles/T-SQL/100061/

    4. […] 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 […]

    5. Rie Irish says:

      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)

    6. kalendelaney says:

      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! 🙂

    Leave a Reply

    Fill in your details below or click an icon to log in:

    WordPress.com Logo

    You are commenting using your WordPress.com account. Log Out / Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out / Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out / Change )

    Google+ photo

    You are commenting using your Google+ account. Log Out / Change )

    Connecting to %s

    Enter your email address to follow this blog and receive notifications of new posts by email.

    Join 1,646 other followers

    Follow me on Twitter

    ToadWorld Pro of the Month November 2013
    %d bloggers like this: