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.
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 (opens WMV).
** @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.