OK people, I don't need a novel written for every line of code, but PLEASE STOP trying to tell me that "yOuR coDe sHouLd bE sELf dOcUmeNtiNg aNd cOmMenTs mEaN iT's aUtoMaTiCaLLy bAd". That's a bunch of BS. I can't begin to tell you how many times I've saved my own butt by dropping a "this call can't be awaited; causes the library's internal API to throw an error" comment in my C#, or a "can't use double quotes here; doesn't work right for some reason" line in my JavaScript. Sometimes there are very good but un-obvious reasons why something was done a certain way, even though it looks like it could be done better. And don't try to tell me "the tests will catch it". Let's be realistic here, nobody has 100% test coverage on any project that's much more than "Hello World". And even if the tests DID catch it, why waste the time when you could just write a comment?

P.S.: This is not directed at anyone on here specifically. It's directed at all the devs I've met IRL and the comments I've seen on SO, who think that comments must be bad.

  • 3
    When you are in-the-zone coding you kind of forget to comment. But there should be a time to review the code when you can do some clean-up and put the comments. Human memory needs a lot of reminding and the comments really do speed up the recollection process.
  • 2
    @iamai Exactly! I'm not suggesting the "getDisplayName()" method needs a "// gets the name for display" comment. But I've had one dev on a project suggest that comments shouldn't be allowed at all. And I think that's ridiculous.
  • 2
    @MySlugLikesSalt they probably haven't had to fix a bug for a program written for quite sometime by them or written by some other programmer. The feels of reading a very long program with very little comments and horrendous flow makes one either want to die in pain or kill in anger.
  • 2
    Comment what needs to be commented, document what needs to be documented and the most important: Keep it uptodate.

    No comments means - as a matter of fact - that at least every individuum who reads the code is left to his own interpretation...

    And I think it's obvious how bad that can end... *cough* standards *cough*
  • 3
    I just can't imagine someone sitting in front of some piece of code and being like: "WTF, why are there comments?!"
    How elitist do you have to be?
  • 1

    > And I think that's ridiculous.

    and its far more important to document the 'why?' way more than the 'what?'

    I've had my share of arguments with 'senior' devs who like to beat up junior devs in code review for not having the XML comment headers. I say, who cares? Unless the header contains 'why' the method/class/whatever is necessary, I don't care. I can read the code and figure out the 'what'.

    A LOT of my comments say things like "Had to hard-code 999 for the quantity check because VP-Bill said if I didn't, I wouldn't have a job. The actual users of this application will eventually want this changed."

    I still get emails from devs saying "Ha ha...read your comment from a month ago when I was told to remove the 999 quantity check because it was stupid."
  • 2
    I am all for minimum comment on the less obvious stuff but I started working with a supposed senior DEV recently who thinks it's just bad practice to write ANY comments and I can't agree with that. Some things are obvious and naming convention covers it but somethings are really not so why waste some why waste someone else's time.
  • 2
    I have put comments in my code that say, "Not sure why this is working." I came back a few days later and saw the comment. Then I took a quick look at the code. I was able to discern why it was working. So I removed the comment. So even in short term comments can be useful to the dev that wrote the comment. There are other areas where there was some tricky code that I commented why it was there. Some things look out of place and might get removed if the reason is not apparent. So I can see comments preventing bugs by devs later on.
  • 2

    I get what you are saying, but not all code documents the why (only the how):

    ListView {

    cacheBuffer: 10000


    This is from a much larger codebase. Obviously this example is cherry picked. But even reading the docs may not describe why this cachebuffer is set. Or set to a large number.


    So why is this set? The comment preceding explains:

    // this is needed to keep listview from stuttering

    The rest of that block is uncommented as the rest is straightforward standard use of properties and functions. So yeah, there needs to be a balance.
  • 2
    I wholeheartedly agree. COMMENTS EXIST FOR A REASON. To explain weird behaviour. People who say comments==bad code are morons who just overheared a "using comments all over the place with irrelevant contents and/or explaining every single thing you do in them means you have wrote code that is not self explanatory" and are trying to play smart by BANNING EVERY SINGLE COMMENT.
  • 0
    @Marl3x You obviously don't work with people who put in comments just to look like they are doing something productive..

    For example comments for docs.. Method had one extra param added, person just copy pasted above comment for a different parameter, left in the wrong type, name and the description..

    So yeah, fuck comments that are useless (even dangerous) because they're plain wrong!! No need to be elitist to hate this shit..
  • 2
    @sladuled I know what you mean.
    I saw comments like: "We need this because blabla...", or like you said simply some copy pasted generated one.
    But still, I've never thought: "Why is there a comment?", I was rather like: "Who the fuck wrote this shit?". It would have still been helpful if the person writing it gave a shit.
    And I was talking about comments that don't necessarily help you, but are just there. I would still rather have something that explains the code a little bit that just have a 100 line method with 20 if statements, that's just there.
Add Comment