Worst Practice - Bad Comments

  • mcroswait

    SSC Rookie

    Points: 43

    quote:


    Just think of the fun you'll have with that!


    At least I have some background with *nix... our developers are REALLY having fun!!!

  • AJ Ahrens

    SSC-Insane

    Points: 20676

    I have inherited a system that has NO comments in it whatsoever. I have added comments as I modify the procedures and have to spend a lot of time researching WHY things happen the way they do.

    I also have a problem with development REFUSING to document the changes. I have brought the value of comments to both my management and their management and their management has determined comments are not needed. Makes my life even worse. Try getting them to use CAPITILIZATION too..

    Thanks for letting me vent

    AJ Ahrens

    SQL DBA

    Custom Billing AT&T Labs



    Good Hunting!

    AJ Ahrens


    webmaster@kritter.net

  • wodom

    Hall of Fame

    Points: 3813

    Tell them telephones aren't needed either, but they sure do save a lot of time & money. And THEY cost a LOT more than comments.

  • cwedgwood50

    SSCommitted

    Points: 1751

    On commenting in general(not just TSQL);

    I think well written, self descriptive code is the most important thing. Every effort should be made to get this right, indents, readable variable names etc.. Then comments to highlight important information that is not obvious from the code. Comments are exceptionally useful, but only when used sparingly, unless teaching code. The fewer comments there are the less chance that future changes will result in comments becoming inadvertantly out-of-sync with the code. I do like a header block at the top though, but think info like last modified should be derived from file save date rather than a comment. It only takes one sloppy programmer to make a change and not comment and that information is wrong!

  • steven powell

    Mr or Mrs. 500

    Points: 557

    One example i came across this week was a lengthy, descriptive and very helpful comment, which related to an old version of the code and as a result was completely meaningless and could've sent me down the wrong path for hours.  In this case the comment was far worse than

    --select * from table1

  • sqltimd

    SSC Rookie

    Points: 49

    In terms of header comments, I don't think I could survive without them. Even on smaller projects, where I'm the only developer, they tend to come in handy. If I have to work on a stored procedure that I wrote several months back, there's a good chance that I won't remember exactly what the sproc does. The header is a good way to "get up to speed" quickly. And for projects where several developers are involved, the "history" section of the header (who changed what, why, and when) can really come in handy.

    As for commenting in general, I guess I tend to think that there's no such thing as "too many" comments. And I probably leave my fair share of what you'd call meaningless (or redundant) comments as well. And here's why: When I first start development of a stored procedure, I write meta code in the form of comments. I basically outline everything that I think the procedure is going to have to do to accomplish the task. Once the meta code is finished, I take a second pass and add the actual TSQL code.

     

     

  • chrisleonard

    SSCertifiable

    Points: 5000

    My favorite teaching example of a useless comment follows:

    Useless comment:

    /* Divide @nh by @nab, storing result in @bav: */

    SELECT @bav = @nh / @nab

    Better comment:

    /* Calculate batting average: */

    SELECT @bav = @nh / @nab

    Granted, this is a "loaded" example, since the variable names are not descriptive, but it illustrates one other issue with comments:  focus on process, not syntax.  In other words, one specific form of a useless comment is one that assumes that the reader can't read whatever language you're programming in.

    I do think that script header comments serve a good purpose, as someone posted earlier.  Not only can you include usage information (I know someone who does this with extended properties, by the way - a nifty idea), but you can "self-document" things like the location of the source file and the change history.  All of this information is useful when you need to change the proc - the usage info gives a sanity check to make sure you know the purpose of the proc, the source location lets you know where to get the code you need to change, and the change history lets you find the idiot whose code you can't understand - or at least realize (with sudden humility) that the idiot is actually YOU. 

    Interesting post.  I had to write a couple pages on comments once for an Exam Cram book (remember those?  the first series of them, I mean...).  Two pages was all I could come up with.  I pulled a copy off of the shelf just for grins, and I can't see anything else I put in there that's not just newbie information...

    Chris

  • John Scarborough

    Ten Centuries

    Points: 1104

    "Bad" commenting is the least of my worries.  Holy cow..  I'm trying to get these people to comment at all!  I'm darned sure not going to complain about how they comment!

    John Scarborough
    MCDBA, MCSA

Viewing 8 posts - 31 through 38 (of 38 total)

You must be logged in to reply to this topic. Login to reply