• @[email protected]
      link
      fedilink
      English
      23 months ago

      a good code doesn’t require comments.

      Commenta should only exist to explain external requirement leading to a functionality being unexpected.

    • exu
      link
      fedilink
      English
      63 months ago

      I’m also not a programmer, you’ll find my longest comments to explain why I’ve done some terrible mangling, what this does and how.

    • Ephera
      link
      fedilink
      English
      283 months ago

      Spamming comments is rather controversial, especially in high-level languages. Problem is, they only show up in one place, so they’re just not very useful, but also have a high chance of becoming inaccurate over time. In particular when you spam them to explain relatively trivial stuff, people will stop reading them, meaning they won’t update them.

      The ‘what’ can be documented with meaningful variable/function names, log/error/assert messages and perhaps most importantly unit/integration tests (which should be understood like a specification that checks automatically that it’s applied correctly).

      Comments are indispensible for explaining the ‘why’, though, whenever that is not obvious.

      • rockerface 🇺🇦
        link
        fedilink
        83 months ago

        Yeah, there’s a balance. If you comment every row of your code, you aren’t naming things clearly. If you never comment, the context is always incomplete.

        • @[email protected]
          link
          fedilink
          3
          edit-2
          3 months ago

          You don’t comment what something does, ir can clearly be seen from the code itself. You comment why you do it.

          • Gumby
            link
            fedilink
            English
            33 months ago

            “Clearly” is also subjective. What might be perfectly clear to me reading my own code may be really confusing to someone else, and vice versa. Especially if the person reading the code isn’t as familiar with the language as the person who wrote it, or if the code is using some syntactic sugar that isn’t super common, or plenty of other reasons.

            • @[email protected]
              link
              fedilink
              33 months ago

              True. It’s more like there’s no need to comment an if statement with “checks if a is larger than b”

  • @[email protected]
    link
    fedilink
    243 months ago

    The people who say “the code is the documentation” totally misunderstood what that was supposed to look like

  • @[email protected]
    link
    fedilink
    English
    53 months ago

    The code is so convoluted the programmer has no idea how it works. Just tables and arrays references each other.

  • Ephera
    link
    fedilink
    English
    663 months ago

    Which is why making code readable is so very important. Our juniors and students will think we’re ridiculous, when we spend a long time cleaning up some code or choosing the least misunderstandable name for a type. But you fuck that up and then others, as well as your future self, will be wasting many more minutes misunderstanding what your code does.

    • rockerface 🇺🇦
      link
      fedilink
      343 months ago

      I treat my future self a few months from now as a separate person who does not remember anything about why or what the specific code fragments do. And I’m grateful to my past self for doing the same.

      Plus, you never know when you need to actually delegate supporting a particular piece of a solution to another person.

      • @[email protected]
        link
        fedilink
        93 months ago

        Write your code as if the next person that works with it is a violent psychopath who knows where you live.

    • @[email protected]
      link
      fedilink
      83 months ago

      Readable code is especially important when companies lay people off every six months so you constantly lose expertise

  • kamen
    link
    fedilink
    53 months ago

    For anything that doesn’t seem entirely obvious I try to leave a comment. It could end up being helpful to me some time later, because let’s face it: your code is indistinguishable from someone else’s code 2 weeks after you commit it.

    • @[email protected]
      link
      fedilink
      23 months ago

      For anything that doesn’t seem entirely obvious I try…

      I’ve come to teach myself that I have no idea what “entirely obvious” is.

      This function is 3 lines long why am I boggled by it right now? I should have written a comment

      • kamen
        link
        fedilink
        English
        33 months ago

        Well, over time, you accumulate some judgment about things like that. But you have some point too.

        • @[email protected]
          link
          fedilink
          23 months ago

          Yeah, it’s honestly mostly an issue of me dipping into programming and not properly sticking to it for long enough to wrap my mind around some concepts. I heard all the warnings that “learning to program is usually one of the hardest things someone has accomplished” because of how late we learn it and all the other complications. I also, however, have heard my whole life that I learned fast and picked things up easily. Boy oh boy was one of those messages more useful than the other lol

  • @[email protected]
    link
    fedilink
    463 months ago

    This made me chortle. I remember when I first joined a dev team asking someone how many of something their section should be able to store:

    I don’t know, I’d have to look at the code.

    It was an eye opening moment. Very few people can keep everything in their head. I’ve met a couple. They were rockstars who were truly exceptional.

    • @[email protected]
      link
      fedilink
      233 months ago

      For me it all depends on how often a project changes. If it’s constantly in flux, I don’t bother remembering any of it because I might not be the last one who touched it. The more you try to remember everything, the more wrong you become due to the successive work of your coworkers.

    • @[email protected]
      link
      fedilink
      243 months ago

      You dont. Thats why you write code that explains itself. For higher level info you write documentation.

        • @[email protected]
          link
          fedilink
          113 months ago

          The only moment you write comments is when you are doing something extremely weird for a specific reason that will not be immediately obvious and you want to warn the person doing a refactor in the future. In any other case, writing self documenting code is the way. If you are unable to do that, then your code needs to be rewrtitten.

          • @[email protected]
            link
            fedilink
            4
            edit-2
            3 months ago

            Mmmm kind of? I wouldn’t categorize most comments as describing “extremely weird” reasons, though. Code will generally explain the “how”, while comments can describe the “why”. For example, think of an enum with ViewSize “mini” and “full”. It might be nice to have a comment to briefly summarize what ViewSize is meant to represent, and maybe link to a spec. Basically, a comment here will connect the intention with the implementation.

            A more inline-comment example of this might be if there’s a slightly nuanced case that you want to be very clear about, ala maybe a Javascript true/false/null case, where you might be checking === false, and specifically don’t want someone to refactor it into a falsy check. Kind of contrived example , but that sort of thing. This is probably more the “extremely weird” comment you’re talking about; almost just a warning that this might not be what you think it is.

            The other common use-case I find good for comments is for summarizing the goals/purpose of a complex function. This is mostly for future people who might utilize this function, and don’t want to read through a bunch of code, just to remember the nuances of what it’s supposed to do. For example, a “sortEvents” function, you may want to summarize the business requirements of the sort at the top. Although, this kind of thing may be different depending on how documentation is stored.

          • @[email protected]
            link
            fedilink
            English
            113 months ago

            Self documenting code is a myth as what’s self documenting to one person is not to the next. Code comments and process/workflow documentation is needed for a healthy codebase.

            • @[email protected]
              link
              fedilink
              13 months ago

              I thought the same, until I spent a few years on a codebase where self-documenting code was enforced with detailed code reviews. That does a very good job of clearing up the ambiguity.

              If you can’t get that kind of review, then by all means use comments.

              • @[email protected]
                link
                fedilink
                33 months ago

                Try handing over your “self documenting code” to a junior dev who doesn’t know the language it’s written in and see how far they get with it.

                Now hand that exact same codebase with comments to the same junior dev, and I guarantee you they’ll get further than without the comments.

                • @[email protected]
                  link
                  fedilink
                  33 months ago

                  I have given well documented code to plenty of juniors, it comes with being a senior dev / techlead. And it was perfectly understood. Maybe you simply don’t write self documenting code.

  • @[email protected]
    link
    fedilink
    23 months ago

    It’s thing! Omni-man says ‘thing’, not ‘part’. I’ve seen this meme format for a few years now and I’ve only just realised it’s a misquote after watching the show. Completely irrelevant nitpick I know but some people might appreciate it.

  • bitwolf
    link
    fedilink
    English
    323 months ago

    Partially yes. But if I create something myself I can “revisit” the headspace of that portion very easily, like I walked into a room.

    Doesn’t work as well on codebases I don’t own fully though.

    • Ephera
      link
      fedilink
      English
      113 months ago

      Yeah, which is why pairing works so well. Suddenly, you’ve got two people who were there when it was created and might know why certain design decisions were made.

  • @[email protected]
    link
    fedilink
    113 months ago

    This one always spoke to me. But I work on embedded systems so I get to fiddle with physical equipment to really make sure the code works.