• marlowe221@lemmy.world
    link
    fedilink
    English
    arrow-up
    8
    ·
    2 months ago

    “Why” comments make more sense as application complexity grows.

    You also have to consider interaction of the code with other external systems - sometimes external APIs force you to write code in ways you might not otherwise and it’s good to leave a trail for others on your team (and your future self…) about what was going on there.

    • something_random_tho@lemmy.world
      link
      fedilink
      arrow-up
      5
      ·
      2 months ago

      100%. I also like to leave comments on bug fixes. Generally the more difficult the fix was to find, the longer the comment. On a couple gnarly ones we have multiple paragraphs of explanation for a single line of code.

    • jonathanvmv8f@lemm.ee
      link
      fedilink
      arrow-up
      1
      arrow-down
      1
      ·
      2 months ago

      I believe you confused the ‘how’ of commenting the ‘why’ with ‘why’ of commenting the ‘why’, if that makes sense.

      I am already aware of and totally agree with the need to document your code in this fashion for the convenience of others and self. What I am troubled about is its implementation in real life. How does one write comment that explains the ‘why’ of the code? How would I know if I haven’t accidentally written something that explains the ‘what’ instead or anything that is simply redundant? It seems like this portion is left out ‘as an exercise for the reader’.

      • marlowe221@lemmy.world
        link
        fedilink
        English
        arrow-up
        5
        ·
        2 months ago

        I think that, in many cases, “what” and “why” are very similar to each other or are closely related.

        I’ve had an experience like this on more than one occasion - I come into an established code base for the first time. I’m working on a new feature/refactor/bug fix. I am reading through a function that is relevant to me, scratching my head a bit, and thinking “I think I see what this function is doing, but why did they do it such a screwy way?” Often there are no comments to give me any clues.

        In the past, I have foolishly changed the code, thinking that I knew better… But what often happens is that I soon discover why my predecessor did something that looked so weird to me. They weren’t stupid - there was a reason for it! And then I end up putting it back…

        Point being, in a situation like that the “what” and the “why” are going to have a lot of overlap. So, personally, I try to write comments that highlight assumptions that won’t be obvious from reading the code, external constraints that matter but don’t actually show up in the code, and so on.

        I am far from perfect at it and I probably don’t write enough comments. But when I do, I try to write comments that will be reminders to myself, or fill in gaps in context for some hypothetical new person. I try to avoid comments that literally explain the code unless it’s particularly (and unavoidably) complex.