• SpeakinTelnet@programming.dev
    link
    fedilink
    arrow-up
    8
    arrow-down
    2
    ·
    11 months ago

    I don’t care how much you think your code is readable, plain text comments are readable by everyone no matter the proficiency in the programming language used. That alone can make a huge difference when you’re just trying to understand how someone handled a situation.

    • Zagorath@aussie.zone
      link
      fedilink
      arrow-up
      7
      arrow-down
      2
      ·
      11 months ago

      Comments explain why, not what. Any comments that explain what a section of code is doing would probably be better off as separated methods.

      Apart from basic documentation comments, like JavaDoc or C#'s XML documentation comments.

      • SpeakinTelnet@programming.dev
        link
        fedilink
        arrow-up
        4
        ·
        11 months ago

        There’s nothing limiting what a comment should be as far as I know.

        As an example of what I mean, I’ve seen in a 10k+ lines python code a few lines of bit manipulation. There was a comment explaining what those lines did and why. They didn’t expect everyone to be proficient in bit manipulation but it made it so that anyone could understand anyway.

        • Zagorath@aussie.zone
          link
          fedilink
          English
          arrow-up
          2
          ·
          11 months ago

          There’s nothing limiting what a comment should be as far as I know.

          Nothing technical, sure. Just good coding practices.

    • Fal@yiffit.net
      link
      fedilink
      English
      arrow-up
      3
      ·
      11 months ago

      There’s nothing keeping the comments up to date with the code. Comments should be sparse and only on sections that aren’t obvious why they’re being done

    • lorty@lemmygrad.ml
      link
      fedilink
      arrow-up
      2
      arrow-down
      1
      ·
      11 months ago

      Then someone needs to change something about the code and doesn’t bother updating the comment. Now you still have uncommented code but with a comment that confuses instead of helping.

      • SpeakinTelnet@programming.dev
        link
        fedilink
        arrow-up
        7
        ·
        11 months ago

        IMHO the issue in this situation is not the comment but that the person updating the code didn’t do his job properly which shouldn’t be an excuse not to do it from the start.