Comment on I am God's greatest programmer

bappity@lemmy.world ⁨11⁩ ⁨months⁩ ago

• xmunk@sh.itjust.works ⁨11⁩ ⁨months⁩ ago

  Commenting well is a highly advanced skill. I generally prefer no comments on code since it’s less likely to confuse people and I’ll merrily purge auto-doc comments and anything like

  // getId() returns an id

  That comment has negative value.

  source

  • kubica@kbin.social ⁨11⁩ ⁨months⁩ ago

    I can't help it, I always get the mental image of hands clapping sarcastically when I see something like that.

    source
  • platypode@sh.itjust.works ⁨11⁩ ⁨months⁩ ago

    In my experience refactoring lots and lots of crappy code left by devs long gone, a dev who can write useful comments is by and large a dev who can write code clean and simple enough not to need them. If the code doesn’t have informative names and clear separation of concern, chances are a comment won’t help because the dev didn’t really know what they did that worked in the first place.

    source

    • MagicShel@programming.dev ⁨11⁩ ⁨months⁩ ago

      Generally, yes. However I have been known to document exactly why I’m doing something incredibly stupid - because it’s required but a stupid third party library which, despite being awful, is still better than implementing it myself as a refactor.

      source
    • bappity@lemmy.world ⁨11⁩ ⁨months⁩ ago

      a dev who can write useful comments is by and large a dev who can write code clean and simple enough not to need them.

      my boss is great in this regard and also always has to keep reminding us to write unit tests 😅

      source
  • magic_lobster_party@kbin.social ⁨11⁩ ⁨months⁩ ago

    Comments should only be used to describe stuff that’s otherwise difficult to convey with code.

    source

    • xmunk@sh.itjust.works ⁨11⁩ ⁨months⁩ ago

      The best explanation I’ve ever heard is:

      Comments should state the ‘Why’ never the ‘What’.

      source

      • hikaru755@feddit.de ⁨11⁩ ⁨months⁩ ago

        There are some cases though where the code is just complicated for reasons outside of your control, in which case “what” comments are good - but they should never be taken at face value, but only used as a first step in understanding the code. There’s a significant risk of the code not actually doing what the comment says.

        source
    • dukk@programming.dev ⁨11⁩ ⁨months⁩ ago

      Yeah. Most of the time I use comments in my algorithms, as they often use some weird optimized black magic which are difficult to understand without comments.

      source

      • DoomBot5@lemmy.world ⁨11⁩ ⁨months⁩ ago

        Like don’t set this value to the obvious default. Bad stuff happens

        source
  • bear@slrpnk.net ⁨11⁩ ⁨months⁩ ago

    I write a lot of fairly simple scripts in Bash and PowerShell that should be easily understood by anybody else with moderate experience in the language, but I leave a lot of obvious comments because my coworkers don’t write any code and are extremely skittish about my automations. I add them basically to quell their fears.

    source

    • odium@programming.dev ⁨11⁩ ⁨months⁩ ago

      Why are coworkers who don’t write any code in the codebase?

      source

      • bear@slrpnk.net ⁨11⁩ ⁨months⁩ ago

        These are scripts that manage stuff on a few hundred user endpoints and a few servers. They were doing basically everything manually until I got here, and the only way I could get them on board with my slow introduction of automation is to let them see it.

        source
  • oce@jlai.lu ⁨11⁩ ⁨months⁩ ago

    I’d rather teach people to comment well through my reviews. Much easier to understand two lines of well written function description in English than 20 lines of code.

    source
• Landless2029@lemmy.world ⁨11⁩ ⁨months⁩ ago

  Yeah well now we have git copilot where your comments include AI suggestions.

  Now I have TONS more comments

  source