Post reply

The Art of Commenting

  • January 4, 2020 at 12:00 am

    #3712250

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

  • January 4, 2020 at 2:52 pm

    #3712368

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

    Rick
    Disaster Recovery = Backup ( Backup ( Your Backup ) )

  • January 5, 2020 at 5:46 pm

    #3712447

    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.

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

  • April 30, 2021 at 6:02 am

    This was removed by the editor as SPAM

  • July 29, 2022 at 9:30 am

    This was removed by the editor as SPAM

Viewing 5 posts - 1 through 4 (of 4 total)

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