• magic_lobster_party@fedia.io
    link
    fedilink
    arrow-up
    5
    ·
    1 month ago

    I think comments are good as a last resort when it’s difficult to communicate the intention of the code with other means.

    If I find code that’s hard to understand, I’ll first try to find better variable or function names. Often this is enough.

    If it’s still too difficult to understand, I try to restructure the code to better communicate the flow of the code.

    If that doesn’t help (or is too difficult), then I might add a comment explaining key information that’s difficult to understand from the code.

    • Pasta Dental@sh.itjust.works
      link
      fedilink
      arrow-up
      3
      ·
      edit-2
      1 month ago

      I think comments are good in a first resort, along with the other points you mentioned. To me reading a single line summary and or explainer will always be faster than reading 15 lines of code even if it’s very well made and self documenting

    • pfm
      link
      fedilink
      arrow-up
      2
      ·
      1 month ago

      As mentioned in my other comment, names will rarely explain the reasons why a given solution was chosen. These reasons are important from maintenance perspective and should be recorded next to the relevant code.

      • magic_lobster_party@fedia.io
        link
        fedilink
        arrow-up
        2
        ·
        1 month ago

        I agree, and I count that as “key information that’s difficult to understand from the code”.

        IMO, comments should be used to provide value to the code. If they’re used too much, then readers of the code will more likely stop reading them altogether. They already got what they need from the code itself and the comments usually don’t add much value.

        If they’re sparse, then that’s a good indication they’re important and shouldn’t be missed.

        • pfm
          link
          fedilink
          arrow-up
          1
          ·
          1 month ago

          I definitely agree that too many comments is often a bad sign, esp. when large part of them is obviously generated.