Commenting your Code

You should always add descriptive comments to any code that will live longer than a single event. It's useful not only for the other unfortunate souls blessed with your code, but for yourself, years later, when you say "what was I thinking here?" I've recently had to debug some code and it is IRRITATING to follow without knowing what on earth this person was thinking. Not that I'm upset or anything. I'm just sayin'.

At the top of your code, you should have a "Comment Block" that describes what the code does, who wrote it, and what changes have been made. Like this:

Title: 002 - Setup SQLCMS.sql
Purpose: Setup the various components for SQL CMS
Version: 1.1
Modification History:
04/30/2009 - Buck Woody - Initial Script Creation
05/15/2009 - Buck Woody - Added MAPS load scripts
Replacement Parameters: (Press CTRL-SHIFT-M To use)
1. SQL Server 2008
2. A database to hold these values. 
1. The Management Data Warehouse feature from SQL Server 2008 to be installed. Enter the name of the MDW database
you create as the "Storage_Database" value.
2. The Microsoft Assessment and Planning Tool installed and configured. Copy over the database creates from the MAPS
tool and run the usp_transfer_MAPS_data stored procedure. 

You should also comments lines where you had to do something..."interesting".

/* I didn't want to have to drop this table, but I didn't see a way around it - I needed to persist the state of the data so a global temp wouldn't work */
DROP TABLE mytable 

You'll notice that I use "block comments" or this: /*  and */. I do this on purpose - you can use two dashes: -- at the start of a line, but it then depends on a linefeed character, which might get copied out. Something like this could happen:

-- Whatever you do, don't type DROP TABLE mytable

And that gets copied wrong or someone presses an enter key, and then this happens:

-- whatever you do, don't type
DROP TABLE mytable

So this is better:

/* This will always be safe. */
/* This will
                always be 
safe */
/* This
safe */


Also - if you're creating a stored procedure, don't do this:

/* This is a really cool stored procedure */

Instead, do this:

/* This is a really cool stored procedure */

Then the comments will stay with the stored proc.

Comments (7)
  1. thulben says:

    I’m wondering what the intent of putting the comment after the ‘create procedure’ command is.  If I do it either way (i.e. header block before or after the ‘create procedure’), the information is stored with the proc.  Both sp_helptext and sys.sql_modules has the information.  If this is the case, is it just a matter of choice?  Or is there something else afoot?

  2. BuckWoody says:

    Well, that’s just preference on my part. It ensures when you’re reading it that you understand that this comment belongs to that stored proc. When I script things out, they can run together, and this keeps it inside the proc defintion.

  3. nappisite says:

    I’m not sure I see the value is prolific code comments.  Code should be self describing and won’t need comments unless its something exceptional or noteworthy. Comments like ‘this selects the customer records’ is redundant if ready the query its obvious that that is what is happening.

  4. BuckWoody says:

    Ah, nappisite, it’s clear you’ve not had to work with other people’s code very often. Debug a few thousand lines of someone else’s code when you’re under the gun and then get back with us.

  5. Totally agree with the value of commenting. It would be nice if code was always self-commenting but that just isn’t going to happen. One thing I’d alter though is to reverse the date order on the "Modification History" section placing the most recent change on top rather than on the bottom. This makes it easier to see who made the last change and what it was.

  6. Saggi Neumann says:

    I prefer comments *after* the create proc statement as well – because when you do perf tuning, looking at blocking processes, etc. – you can also get the sql text and if it starts with a few lines of comments before the sproc’s name it can be frustrating.

  7. Brian Tkatch says:

    In one class in college, i wrote a large comment. My instructor, though jokingly, mentioned large comments are bad, because noone wants to keep them up to date!

    Personally, i use — for commenting. /* */ wastes two extra spaces on the line. :) Ans i try to keep comments concise enough for one line. In general, i find this makes it easier to understand. Verbosity is nice, but usually cumbersome.

    Nonetheless, i do have larger comments when explaining complex options, such as in a CASE statement when the individual cases aren’t clear. Or at the beginning of a process, where it does many steps that need their consistency explained.

    In those cases, i still use –. I think it makes it look nicer.

    — This is a comments about options:

    — 1) Option 1 is Buck Woody.

    — 2) Option 2 is Chuck Norris.

    — 3) There is no option 3.

    I think that looks much nicer than:

    /* This is a comments about options:

    1) Option 1 is Buck Woody.

    2) Option 2 is Chuck Norris.

    3) There is no option 3.


    It looks nicer (to me) because the — keeps the comment context obvious, and lines up well.

    I usually use /**/during debugging, to easily block/unblock code.

Comments are closed.

Skip to main content