• Martin@feddit.nu
    link
    fedilink
    arrow-up
    75
    arrow-down
    1
    ·
    4 months ago

    Comments should explain “why”, the code already explains “what”.

    • smeg@feddit.uk
      link
      fedilink
      English
      arrow-up
      63
      ·
      edit-2
      4 months ago

      The allowable exception is when the what is a what the fuck, as in you had to use a hack so horrible that it requires an apology comment

      • Martin@feddit.nu
        link
        fedilink
        arrow-up
        15
        ·
        4 months ago

        Absolutely, although I see that as part of why

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

      • lad@programming.dev
        link
        fedilink
        English
        arrow-up
        5
        ·
        4 months 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

      • bleistift2@sopuli.xyz
        link
        fedilink
        English
        arrow-up
        4
        ·
        4 months ago

        Describing the what also helps when you dabble in a new technology or little-used technology. It helps to explain to yourself what you’re doing and it helps in onboarding. “Hey, newbie, there’s a function in XYZ module that’s extensively documented. Look there for guidance.”

        • MystikIncarnate@lemmy.ca
          link
          fedilink
          English
          arrow-up
          6
          ·
          4 months ago

          I don’t code, at best I script. I’m a sysadmin, not a dev, so I play around in PowerShell mostly.

          I just started to naturally do all of this. Not because I was taught to, but because I’ve written too many scripts that I later looked at, and thought, WTF is going on here… Who tf wrote this? (Of course it was me)…

          So instead of confusing my future self, I started putting in comments. One at the beginning to describe what the file name can’t, and inline comments to step me through what’s happening, and more importantly why I did what I did.

          The sheer number of comments can sometimes double the number of lines in my script, but later when I’m staring into the abyss of what I wrote, I appreciate me.

      • myplacedk@lemmy.world
        link
        fedilink
        arrow-up
        1
        ·
        4 months ago

        I agree.

        I usually think of that as documentation, not comments.

        But even so, the code should say what it does, with a good name. The documentation adds details.

    • azdle@news.idlestate.org
      link
      fedilink
      English
      arrow-up
      5
      ·
      4 months ago

      Unless you’re working with people who are too smart, then sometimes the code only explains the how. Why did the log processor have thousands of lines about Hilbert Curves? I never could figure it out even after talking with the person that wrote it.