Slash star, dash dash: Be obsessive about comments

I’m working on a new session* that I’ve named “T-SQL’s Hidden Support Feature”. It’s about comments. I’ll get to the reasons why I’m writing and presenting an hour long session on /* */ and — a bit later, but first: Why am I calling comments a “hidden support feature”?

Comments themselves aren’t hidden; it’s the idea of comments as a support feature that’s stuck back behind the curtains somewhere. You see, I can’t find a single blog anywhere about comments. (Well, I found one, but it was comparing comment features between RDBMSs.)

Comments support code

Comments are a form of documentation. One of the best forms, if you do it right. And documentation supports code…rather, makes it more supportable, by making it more understandable to those who need to deal with it.

In what ways do comments beat traditional documentation?

• Comments actually get written. Few IT professionals like to stop coding to go write about their code. But most of us can be convinced to jot down applicable notes AS we code.
• They’re handy-dandy, readily available. Comments are not a separate document. So they’re always with the relevent code, instead of being hidden away in some aged-out, unused server that no one knows about. The people that NEED them will SEE them, when they open the SP (or function, or view, etc.)
• They’re easy to update. NOBODY likes to update documents. Fix code, open doc, change doc, save doc. Nope nope nope. But, if the “documentation” is right there IN the code, I can modify it as I modify the code.

Plant some comments in a flower box

Let’s take the Minion.BackupMaster SP as an example. Download MB and follow along at home, if you like, or just press on without detailed visual aids.

Right there at the top, we’ve got some information about one of the parameters. With a little bit of looking, most of the other parameters are (rather, might be?) largely self explanatory. But @Include has some interesting options that wouldn’t be noticed without digging into the code.

After that we have what’s called the “flower box”: the big slash-star comment at the top of an object that has a lot of standard information**, like:

• who wrote the object (and any copyright or source URL)
• when it was written
• what it’s for
• modification log

That’s already a lot of good information. I can’t tell you how many stored procedures I’ve opened up, only to wish I knew who owned it, how old it was, when it was last modified, or what in god’s name anyone thought it might be useful for.

We like to add more, even more useful, information to this flowerbox:

• other information and resources about our organization(s)
• what the parameters are for. (Remember how I said that most params are self explanatory? They aren’t. Document them.)
• what temporary tables are created, and how they’re used
• example execution statements (for a stored procedure or function)
• table of contents (SP / function)

All of this stuff is useful to me, as the author – because coders write a lot of code, and we’re going to forget the nuances in about a week’s time. And it’s useful to me as the support staff, because I might have no earthly idea what @ReadOnly is for. It’s a LOT easier and faster – not to mention more accurate – to get a short explanation in the flower box, than it is to tear this entire 2,500 stored procedure (and any dependent objects) apart.

END;

I don’t want to give away the whole session. In fact, I don’t even want to give away the whole first 10 minute section of the session. You’ll have to wait until I give it at SQL Saturday Oklahoma City (or, until the recording is posted afterward).

But start with the flower boxes. Get into that habit; make your code more supportable.

-Jen
http://www.MidnightDBA.com/Jen

*The session started in my head years ago, and launched a few weeks ago when I was double-dog-dared to write it by Oklahoma City user group members. As some wise cartoon character said, friends can get one into such trouble.

** @EdDebug pointed out that the source and modification log I mentioned should really be taken care of by the use of source control. I agree. I also know that many of the organizations that I’ve been in do not use source control for their SQL code. With any luck, the trend is changing,