• Shoe@lemm.ee
      link
      fedilink
      arrow-up
      1
      ·
      2 years ago

      Have reviewed 16 year old code for a very well known company in the last week with this exact comment peppered throughout, alongside delightfully helpful comments like:

      // do not delete or change this it just works

      // TODO temporary fix added 12/09/11 to fix incident must be removed ASAP

      // CAUTION this returns false here instead of true like it normally does, not sure why

      // if true then matched to valid account not is true

  • SlopppyEngineer@lemmy.world
    link
    fedilink
    arrow-up
    2
    ·
    2 years ago

    Best comment ever was “It used to work like this but person at client demanded it work like that on this date” when the client complained it shouldn’t work like that.

    • T. Hex@lemmy.dbzer0.com
      link
      fedilink
      arrow-up
      2
      ·
      2 years ago

      The best comments are “why” comments, the runner up is “how” comments if high-level enough, and maybe just don’t write “what” comments at all because everyone reading your code knows how to read code.

    • conciselyverbose@sh.itjust.works
      link
      fedilink
      arrow-up
      2
      ·
      2 years ago

      That’s basically what comments are most useful for. When you’re doing something that’s not obvious, and want to make sure the “why” doesn’t get lost to time.

      • ChickenLadyLovesLife@lemmy.world
        link
        fedilink
        English
        arrow-up
        1
        ·
        2 years ago

        I spent a year making my company’s iOS apps accessible (meaning usable for the blind and people with vision disabilities). I had to do a lot of weird shit either because of bugs in Apple’s VoiceOver technology or because of the strange way in which our code base was broken up into modules (some of which I did not have access to) and I would always put in comments explaining why I was doing what I was doing. The guy doing code review and merges would always just remove my comments (without any other changes) because he felt that not only were comments unnecessary but also they were a “code smell” indicating professional incompetence. I feel sorry for whoever had to deal with that stuff at a later point.

        • lad@programming.dev
          link
          fedilink
          English
          arrow-up
          0
          ·
          2 years ago

          Well, this is shitty

          I hope the reviewer did not also squash commits, and the next programmer would be able to at least dig what was there.

          Doing changes after some rockstar dev implemented some really complex service, but left no clues as to what does what is so frustrating, and I can never be sure that I don’t break anything in a different place completely

          • ChickenLadyLovesLife@lemmy.world
            link
            fedilink
            English
            arrow-up
            1
            ·
            2 years ago

            I meant to say commits and not merges, and yes he removed the comments before committing. It made no difference in long run because every new release broke all the accessibility stuff anyway. It’s amazing how little developers can be made to care about blind people - almost as little as managers. The only reason my company cared at all was they were facing million-dollar-a-month fines from the FCC.

    • jaybone@lemmy.world
      link
      fedilink
      arrow-up
      1
      ·
      2 years ago

      That’s actually the perfect comment, because if anyone ever comes back to fuck with you about it, it’s explained right there. Then you turn it right back around on management and watch them run around like chickens with their heads cut off.

      • lad@programming.dev
        link
        fedilink
        English
        arrow-up
        0
        ·
        2 years ago

        Or if the what is so cryptic and esoteric that it would require the reader a couple hours of research to understand it.

        Also, I find it useful to summarise the what before code blocks if that can’t be summarised in a function name

      • Martin@feddit.nu
        link
        fedilink
        arrow-up
        0
        ·
        2 years ago

        Absolutely, although I see that as part of why

        Why is there a horrible hack here? Because stupid reason…

  • ImpulseDrive42@lemmy.world
    link
    fedilink
    arrow-up
    0
    ·
    2 years ago

    I had a old job that told me that code is “self documenting” if you write it “good enough”. And that comments were unnecessary.

    It always annoyed the heck out of me. Comments are imo more helpful than hurtful typically.

    Is it just me? Or am I weird? Lol.

    • Blackmist@feddit.uk
      link
      fedilink
      English
      arrow-up
      0
      ·
      2 years ago

      Code is the what. Comments are the why.

      Few things worse than an out of date comment.

    • VonReposti@feddit.dk
      link
      fedilink
      arrow-up
      0
      ·
      2 years ago

      Code should always by itself document the “how” of the code, otherwise the code most likely isn’t good enough. Something the code can never do is explain the “why” of the code, something that a lot of programmers skip. If you ever find yourself explaining the “how” in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.

      For me, that’s what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.

      • ChickenLadyLovesLife@lemmy.world
        link
        fedilink
        English
        arrow-up
        0
        ·
        2 years ago

        lazy programmers

        I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.

    • Vigge93@lemmy.world
      link
      fedilink
      arrow-up
      0
      ·
      2 years ago

      Comment should describe “why?”, not “how?”, or “what?”, and only when the “why?” is not intuitive.

      The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

      E.g. Good comment: “This workaround is due to a bug in xyz”

      Bad comment: “Set variable x to value y”

      Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained

  • KillingTimeItself@lemmy.dbzer0.comBanned
    link
    fedilink
    English
    arrow-up
    0
    arrow-down
    1
    ·
    2 years ago

    this is why i very rarely comment with descriptive comments. If you’re reading my code and don’t understand what it is, even with how shit it is, you have no business reading whatever fucking crackpot shit im writing.