• Simulation6@sopuli.xyz
    link
    fedilink
    arrow-up
    0
    ·
    1 month ago

    Figuring out what the code is doing is not the hard part. Documenting the reason you want it to do that (domain knowledge) is the hard part.

    • steventhedev@lemmy.world
      link
      fedilink
      arrow-up
      0
      ·
      1 month ago

      One upvote is not enough.

      I once wrote a commit message the length of a full blog post comparing 10 different alternatives for micro optimization, with benchmarks and more. The diff itself was ten lines. Shaved around 4% off the hot path (based on a sampling profiler that ran over the weekend).

    • tatterdemalion@programming.dev
      link
      fedilink
      arrow-up
      0
      ·
      1 month ago

      Agreed.

      And sometimes code is not the right medium for communicating domain knowledge. For example, if you are writing code the does some geometric calculations, with lot of trigonometry, etc. Even with clear variable names, it can be hard to decipher without a generous comment or splitting it up into functions with verbose names. Sometimes you really just want a picture of what’s happening, in SVG format, embedded into the function documentation HTML.

      • hex@programming.dev
        link
        fedilink
        arrow-up
        0
        ·
        edit-2
        1 month ago

        Yeah. I advocate for self explanatory code, but I definitely don’t frown upon comments. Comments are super useful but soooo overused. I have coworkers that aren’t that great that would definitely comment on the most basic if statements. That’s why we have to push self explanatory code, because some beginners think they need to say:

        //prints to the console
        console.log("hello world");
        

        I think by my logic, comments are kind of an advanced level concept, lol. Like you shouldn’t really start using comments often until you’re writing some pretty complex code, or using a giant codebase.

        • Faresh@lemmy.ml
          link
          fedilink
          English
          arrow-up
          0
          ·
          1 month ago

          Comments are super useful but soooo overused

          I think overusing comments is a non-issue. I’d rather have over-commented code that doesn’t need it, over undocumented code without comments that needs them. If this over-commenting causes some comments to be out of date, those instances should hopefully be obvious from the code itself or the other comments and easily fixed.

          • hex@programming.dev
            link
            fedilink
            arrow-up
            0
            ·
            1 month ago

            I understand what you’re saying and I mostly agree, but those few instances where a line of code is only slightly different and the comment is the same, can really be confusing.

    • lobut@lemmy.ca
      link
      fedilink
      arrow-up
      0
      ·
      1 month ago

      I can’t recall the exact change but a coworker did something five years very intentionally. The comments, the commit and everything described what they did but not why.

      I think it was with side effects: true and I fixed a certain way we bundled things and I believe that could have solved the issue but I don’t know for sure :/