• xmunk@sh.itjust.works
      link
      fedilink
      arrow-up
      18
      ·
      1 year ago

      The best explanation I’ve ever heard is:

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

      • hikaru755@feddit.de
        link
        fedilink
        arrow-up
        1
        ·
        1 year 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.

    • dukk@programming.dev
      link
      fedilink
      arrow-up
      3
      ·
      1 year 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.