The Worst Comments

  • Stuart Davies

    SSCoach

    Points: 18813

    Phil Parkin (3/13/2015)


    Superfluous comments are worse than no comments. You know the type:

    --Find the average

    select @avg = avg(x)

    Reminds me of those people who, when doing presentations, just recite what is written on screen.

    +1

    +1 to no comments too.

    Worse one I've come across "If you need comments to understand this - you shouldn't be looking"

    -------------------------------Posting Data Etiquette - Jeff Moden [/url]Smart way to ask a questionThere are naive questions, tedious questions, ill-phrased questions, questions put after inadequate self-criticism. But every question is a cry to understand (the world). There is no such thing as a dumb question. ― Carl Sagan I would never join a club that would allow me as a member - Groucho Marx

  • Emil B

    SSCertifiable

    Points: 5568

    The worst commenting, not comment, ever was when i found my stored procedure is not working for some reason:

    CREATE PROCEDURE dbo.Procedure

    AS

    ---BEGIN

    ---The whole procedure code commented

    ---END

    Not sure if it counts as the worst comment but...

  • Eirikur Eiriksson

    SSC Guru

    Points: 182344

    Gary Varga (3/13/2015)


    Toby Harman (3/13/2015)


    Many years ago I found a comment by my boss in the code which read something along the lines of

    -- Don't touch this code

    -- It does fancy statistical maths on an iterative loop until it gets the answer

    -- Really, don't touch it

    -- Even if you think you kn ow what you are doing, DON'T

    It served one useful purpose. It warned me that the next page was complex. It didn't tell me anything about what it was actually doing!

    Sometimes quotes say a lot more about the author than the reader.

    Take it that you meant "more about the author than the code", the other is really really spooky

    😎

  • Emil B

    SSCertifiable

    Points: 5568

    Stuart Davies (3/13/2015)


    Worse one I've come across "If you need comments to understand this - you shouldn't be looking"

    +1 :hehe:

  • Gary Varga

    SSC Guru

    Points: 82166

    Stuart Davies (3/13/2015)


    Phil Parkin (3/13/2015)


    Superfluous comments are worse than no comments. You know the type:

    --Find the average

    select @avg = avg(x)

    Reminds me of those people who, when doing presentations, just recite what is written on screen.

    +1

    +1 to no comments too.

    Worse one I've come across "If you need comments to understand this - you shouldn't be looking"

    Yes!!! Commented out code. That's what source code control is for. If you need to leave a reference to old code then just leave a comment WHY it was removed with a date. Commented out code alone just says "this is code we are not using". I don't care unless I know WHY and even then I don't want a third of the code to be that which is deemed no longer relevant!!!

    Gaz

    -- Stop your grinnin' and drop your linen...they're everywhere!!!

  • Gary Varga

    SSC Guru

    Points: 82166

    Eirikur Eiriksson (3/13/2015)


    Gary Varga (3/13/2015)


    Toby Harman (3/13/2015)


    Many years ago I found a comment by my boss in the code which read something along the lines of

    -- Don't touch this code

    -- It does fancy statistical maths on an iterative loop until it gets the answer

    -- Really, don't touch it

    -- Even if you think you kn ow what you are doing, DON'T

    It served one useful purpose. It warned me that the next page was complex. It didn't tell me anything about what it was actually doing!

    Sometimes quotes say a lot more about the author than the reader.

    Take it that you meant "more about the author than the code", the other is really really spooky

    😎

    No. Not at all. The author assumes that the reader will not understand the code. To me it suggests that the author doesn't. Otherwise it would be clearly commented and readable. Even if very complicated and difficult to understand.

    Gaz

    -- Stop your grinnin' and drop your linen...they're everywhere!!!

  • Phil Parkin

    SSC Guru

    Points: 243485

    Gary Varga (3/13/2015)


    Yes!!! Commented out code. That's what source code control is for. If you need to leave a reference to old code then just leave a comment WHY it was removed with a date. Commented out code alone just says "this is code we are not using". I don't care unless I know WHY and even then I don't want a third of the code to be that which is deemed no longer relevant!!!

    I think commented-out code says this:

    "I may have removed code which is still required – I'm just not sure. But if I leave it here, I lessen the problem, because it will be very easy for some other developer, who actually knows what they are doing, to resurrect. I don't really understand source control."

    😀

    If the answer to your question can be found with a brief Google search, please perform the search yourself, rather than expecting one of the SSC members to do it for you.

  • Phil Parkin

    SSC Guru

    Points: 243485

    Going off on a slight tangent, what about bad error messages?

    I've just had this one in SSIS:

    Executing the query "exec ..." failed with the following error: "Package execution failed with status: Failed

    Thanks for that.

    If the answer to your question can be found with a brief Google search, please perform the search yourself, rather than expecting one of the SSC members to do it for you.

  • Gary Varga

    SSC Guru

    Points: 82166

    Phil Parkin (3/13/2015)


    Going off on a slight tangent, what about bad error messages?

    I've just had this one in SSIS:

    Executing the query "exec ..." failed with the following error: "Package execution failed with status: Failed

    Thanks for that.

    My favourites (sic) are the ones that say something akin to "Error: No error detected". Was there a problem? Wasn't there a problem? I am left unsure.

    Gaz

    -- Stop your grinnin' and drop your linen...they're everywhere!!!

  • call.copse

    SSCoach

    Points: 16747

    dwain.c (3/12/2015)


    MLK44 (3/12/2015)


    .

    +1. What's worse: bad comments or no comments?

    In general I would say definitely bad comments - they can confuse or obscure what is going on. Typically when you encounter a sloppy hack and slash coder's work you'll find comments attributable to other methods from which the code was hacked, and which have not been edited to be sensible. This requires extra, pointless time to parse and discard. Comments need to be maintained to be of any use.

    There are plenty of times when no comments are needed or useful, with appropriate naming and structure. I'll always tend to favour sparser commenting - to communicate intent - with good structure in my coding style.

  • J^M

    SSC Journeyman

    Points: 75

    My favorite, found in a long stored procedure:

    ------------- CAREFUL -------------

  • samo 19780

    SSC Enthusiast

    Points: 107

    My favourite bad comment is

    "recreated it by using more functions instead of joins"

    Followed by a nest of scalar functions and while loops. It happens to be one of the worst offenders for timeouts in our application. I've had a stab at speeding it up, but at almost 800 lines I just get lost in it.

    I suppose the comment itself isn't so bad, it does describe the problem - just what it represents!

  • Ian Rennie

    SSC Journeyman

    Points: 95

    I remember seeing the comment "What has she done now?". Unfortunately, apart from the discourtesy, the author had not checked how his code rendered - it appeared in an email to tens of thousands of his organisation's customers

  • Robert Sterbal-482516

    SSCrazy

    Points: 2784

    Reference comments are highly appreciated. If someone take the time to tell me where to look up a request that prompted the code it saves me a bunch of time searching for and guessing for the relevant issue.

    In general I find any comment instructive because of all the places the person didn't decide to put in comments.

  • BenWard

    SSCertifiable

    Points: 5903

    Stuart Davies (3/13/2015)


    Worse one I've come across "If you need comments to understand this - you shouldn't be looking"

    Guilty....

    Here's an extract from some system documentation I wrote a few years ago:

    Now, it handles the load date in a similar way as described in the previous paragraph but it does it all in some sub queries – I have spent a good few minutes staring at these sub queries and I'm not 100% sure I can work out exactly how I did it now. Maybe if it wasn't after 4PM and I wasn't flagging from all the caffeine I had earlier on I'd be able to write something sensible here about it. You're a programmer. You work it out.

    Fortunately this relates to code that only had to run for 1 year and is therefore no longer in production use...

    Ben

    ^ Thats me!

    ----------------------------------------
    01010111011010000110000101110100 01100001 0110001101101111011011010111000001101100011001010111010001100101 01110100011010010110110101100101 011101110110000101110011011101000110010101110010
    ----------------------------------------

Viewing 15 posts - 16 through 30 (of 157 total)

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