• 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.