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.

MB1

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,

12 thoughts on “Slash star, dash dash: Be obsessive about comments

  1. Nic

    I would also say that in using comments, stick to a single kind of comment style.

    Either use /* */ or — throughout, don’t mix the two.

  2. Cad Delworth

    Hmph!

    Well, Ms MsCown, I’m upset. Please don’t claim that “NOBODY likes to update documents.” because for your information, I genuinely **LOVE** updating documents: almost MORE than I enjoy coding.

    Also FYI “relevent” [sic] is spelt “relevant,” even in a US dictionary. 😛

    Cad Delworth
    Edinburgh, Scotland

    1. Jen McCown Post author

      You are a gem among humans, Cad. Clearly there are certain nonzero values of “someone” that so like updating documents, but the number is statistically insignificant. 🙂

  3. Carl Brandrick

    Great article and I think this will be a great session as people don’t realise how useful comments are until they haven’t got any and wish they did.

    I’ll be looking out for the posted recording after the event

  4. Kevin Fries

    I normally write the comments before I write a line of code. That’s normally the program narrative, testing and usage instructions and routine stubs. It helps me to keep the program design and flow from spiraling out of control from scope creep and revisions.
    That doesn’t mean I won’t revise, delete or add more but it helps with complicated driver programs that call external procedures/programs.
    Flowcharts are nice but they are a pain to maintain and it’s easier for someone to see the whole picture when it’s in one place. Try following a flowchart at 3am when you’ve never seen the program.
    It’s also easy to provide a final document by simply pulling out the working comments from the “finished” source.

    I’ve gotten complaints about verbiage but TMI is better than TLI.

  5. Roger Plowman

    Finally! Somebody is talking about comments as a good thing. Personally, my code is heavily commented, usually 50% by line count for T/SQL, even higher for VB or Python.

    Six months later you WON’T remember what your code does–but your comments will!

  6. Stephanie Brown

    +1 with Cad! My nickname is “The Documentation Queen”.

    Hope you’ll be reminding everyone to put the “why” in the comments. While putting the “what” is great for complex code, the question I’m most often trying to answer these days is “why did they do that?” or “why did they do it THAT way?”

Comments are closed.