I’m working on a new session named “T-SQL’s Hidden Support Feature”, about T-SQL comments. Why on Earth 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.
Side note: Of course I’m using our own code as examples. For one thing, the Minion modules and Minion Enterprise are easily the biggest projects that we’ve had the sole responsibility for. That means that we have sole discretion on how comments are used in the code. But for another, Minion Backup and Minion Reindex are completely free and open, so you can do your own looking around in the code, at the comments.
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. I’ll post the recording once that’s ready, but for now…start with the flower boxes. Get into that habit; make your code more supportable.
Update: Here is the recording! T-SQL Hidden Support Features
** @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, but we still need strategies for the shops less inclined to be formal.