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