The Art of Commenting

  • Steve Jones - SSC Editor

    SSC Guru

    Points: 720371

    Comments posted to this topic are about the item The Art of Commenting

  • skeleton567

    SSCertifiable

    Points: 5096

    One of the greatest values of commenting is to answer the proverbial 'What was I thinking ?' question.

    Rick

    The only thing worse than being an influencer
    is believing one.

  • Jeff Moden

    SSC Guru

    Points: 996809

    skeleton567 wrote:

    One of the greatest values of commenting is to answer the proverbial 'What was I thinking ?' question.

    Heh... spot on.  I use comments for the following...

    1. To reiterate what you said, "What was I thinking".
    2. In the same vein as #1, I always add my name in the "Revision History" in the flower box so that I don't actually blame anyone else for "crap code" from my younger days.
    3. More importantly and as a bit of a lost art, I'll frequently make a flow chart for some of the more complex things I write.  Then, I'll transfer the descriptions of the blocks in the flowchart to the code in the form of comments.  Then I just fill in between the comments with code that accomplishes the each comment.  It helps me to keep from losing my place and allows me to concentrate on each sub-task without being distracted about what I just did or what I need to do next.  It reminds me to "peel just one potato at a time" and I get things done not only more quickly but the code seems to come out a whole lot better.  It also means that I don't have to go back and write comments to help others quickly isolate which section of code people need to work on for future modifications or troubleshooting.  I'll also include one of more working "usage" examples so that some poor slob that's trying to troubleshoot or modify the code can actually run the usage examples to see how things currently work.  I also expect the folks I work with to update any comments or usage examples that change because <drumroll please>, I think they're that important.  If that slows someone down, my answer is, "good... you need to slow down and do it right the first time because it takes 8 times longer or more to do it a second time not". 😀

    That latter method help us reach a very near "zero defect" rate and dropped the time it took for sometimes simple modifications (and, certainly for major ones) from a typical day or two to just an hour or two and still delivered at a very near "zero defect" rate.

    On the flip side of the coin, comments such as "Update the Customer table" are near totally useless.  My rule of thumb is that if you were to remove all of the code, the comments that remain could be used to draw a functional flowchart along with a bit of "Alice's Restaurant" comments that explain difficult to understand pieces of code.

    The cool part about comments is that they automatically travel with the code.  You don't necessarily have to go looking for requirements documents, flow charts, etc, etc, when you're trying to figure out what the hell the code is supposed to be doing.

    I even use comments (especially flower box comments) in BCP format files.  Anything below the number of rows assigned  in the second line of the format file is ignored by SQL Server.  And, yeah... you can put some pretty weird stuff into a format file that others might not understand like why the first column has been assigned a width of one and will only ever contain a single double-quote of why I'll typically assign a column width of 500 even though I know that the column should never have a width greater than 4 characters (for example).

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.
    "Change is inevitable... change for the better is not".
    "If "pre-optimization" is the root of all evil, then what does the resulting no optimization lead to?"

    Helpful Links:
    How to post code problems
    How to Post Performance Problems
    Create a Tally Function (fnTally)

Viewing 3 posts - 1 through 3 (of 3 total)

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