Comments – The Real Deal

Last Updated on March 15, 2015 by John Morehouse

To comment or not to comment, that is the question!

I’m not referring to the comments made verbally but rather comments in your code. They are a vital piece of code that I see disappearing from code (especially from procedures) and this frustrates me.

There are arguments out there for NOT putting comments in code; that your code should “tell the story” to the reader. Personally I think that’s horse crap. Trying to read someone’s code in the attempts of figuring out WHY they are doing things the way that they did is near impossible. I can see HOW they are doing things via the code but the why is more important.

This is especially true when doing deployments. When you send your code to your production DBA to deploy, if they are worth their weight they are reviewing your code. Well, if they aren’t doing that they really should. If you don’t include comments it’s very difficult to determine some things later in life:

  1. Who touched the Code last
  2. When the change was put into place
  3. What you might have changed
  4. Why things changed
By the way, I think that this list is also ordered in the order of importance.

The Who

If you don’t put your name on the code then when things break it can be difficult to track down who made the change. When it breaks at 2AM, it’s really a pain. When that happens I want to make sure that I’m calling the right person when I have to. Otherwise there is a chance that I’ll have to do a phone tree and wake up multiple people to find the right person.   Some of you might be asking, why do I call? Why not just fix it and move on? Well, often times I know how to physically fix the issue but what I don’t know is the business ramifications of the fix.  I like to be as informed as possible when fixing production issues, thus I call folks when needed.

In the event that I am able to resolve the issue myself, I still won’t know who to follow up with in the morning unless it’s in the comments. I could guess, I but after being up at 2AM, I’d rather not play “Where In The World Is That Person Who Wrote This?” game.

The When

When the code was last touch is just as important as the Who. This will help me to correlate the change with the change control process as well as any other documentation that might be available. It essentially gives me another point of reference that I can use.

If you don’t have a change control process in place, you should really get one.

The What

I think some people think that comments have to be large and detailed. They don’t. Honest, they just don’t. They just need to quickly and easily tell a short story. You can do this very easily just by including a line that has a quick blurb on why changed. It’s that simple.  If you can tweet stuff in 140 characters or less, you can leave a comment.  

The Why

This to me is the optional piece of the comment. It’s a great to have and helps keep everybody’s sanity. If you can explain your logic behind the change, great!! If not, do the best that you can.

At the very least, if you can include Who & When, I’ll be happy with that. By providing me with that information I can at least go back to that specific individual and start to ask questions. I can fill in the What & Why through that conversation.

But if you don’t provide any of that or the comments are in a place that I don’t know about (IE: source control) then I’m somewhat screwed and have to make the best of it.

Source Control

Some will argue that all of the comments should go into source control. Great! I agree!! Are all of your databases in a proper database project and then tied to source control? Are all of your scripts in source control? If not, then tough luck. I would bet that most shops haven’t yet adopted putting their databases into source control. Until that happens (and it should), put your comments in the code.

I can assure you that at 2AM looking at the source control is going to be my last stop.

Example

Here is an example of a comment block that you can include in your stored procedures. You are welcome to modify it anyway shape or form.

/********************************************
Author: John Morehouse
Created On: 8/19/13

Modified History:
20130819 MorehouseJ: Added a join to tableA for Story123
*********************************************/

It’s that simple folks. Not real fancy is it?  If you wanted to, you could even make yourself a template in SSMS to use for when you are creating a new procedure/view/function. This would ensure that all new procedures would have some sort of comment.

As someone who supports the production environment, these few lines of code mean a lot to me when I have to trouble shoot issues.  Oh, and believe me when I say that I do indeed look at the comments.

So do your DBA a favor. Put comments in.  It’ll only take you 30 seconds to do.

© 2013 – 2015, John Morehouse. All rights reserved.

3 Replies to “Comments – The Real Deal”

Hey you! Leave me a comment and start a discussion!

This site uses Akismet to reduce spam. Learn how your comment data is processed.