• ImpulseDrive42@lemmy.world
    link
    fedilink
    arrow-up
    61
    arrow-down
    4
    ·
    6 months ago

    I had a old job that told me that code is “self documenting” if you write it “good enough”. And that comments were unnecessary.

    It always annoyed the heck out of me. Comments are imo more helpful than hurtful typically.

    Is it just me? Or am I weird? Lol.

    • VonReposti@feddit.dk
      link
      fedilink
      arrow-up
      35
      ·
      6 months ago

      Code should always by itself document the “how” of the code, otherwise the code most likely isn’t good enough. Something the code can never do is explain the “why” of the code, something that a lot of programmers skip. If you ever find yourself explaining the “how” in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.

      For me, that’s what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.

      • ChickenLadyLovesLife@lemmy.world
        link
        fedilink
        English
        arrow-up
        16
        arrow-down
        2
        ·
        6 months ago

        lazy programmers

        I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.

        • Dropkick3038@programming.dev
          link
          fedilink
          arrow-up
          1
          ·
          6 months ago

          And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.

    • Vigge93@lemmy.world
      link
      fedilink
      arrow-up
      28
      ·
      edit-2
      6 months ago

      Comment should describe “why?”, not “how?”, or “what?”, and only when the “why?” is not intuitive.

      The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

      E.g. Good comment: “This workaround is due to a bug in xyz”

      Bad comment: “Set variable x to value y”

      Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained

      • balp@lemmy.world
        link
        fedilink
        arrow-up
        2
        ·
        6 months ago

        Docstring are user documentation, not comments. User documentation, with examples (tests), is always useful.

        • Vigge93@lemmy.world
          link
          fedilink
          arrow-up
          2
          ·
          6 months ago

          As long as it’s maintained. Wrong documentation can often be worse than no documentation.

    • Blackmist@feddit.uk
      link
      fedilink
      English
      arrow-up
      13
      ·
      6 months ago

      Code is the what. Comments are the why.

      Few things worse than an out of date comment.

    • homura1650@lemm.ee
      link
      fedilink
      arrow-up
      11
      ·
      6 months ago

      Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being “This is the <variable name>, or this does <method name>”. Beyond, being useless, those comments are counter productive. The amount of screen space they take up (even if greyed out by the IDE) significantly hurts legability.

        • EpeeGnome@lemm.ee
          link
          fedilink
          English
          arrow-up
          4
          ·
          6 months ago

          The issue with having mandatory useless comments is that any actually useful comments get lost in the noise.

          • Alexstarfire@lemmy.world
            link
            fedilink
            arrow-up
            3
            ·
            6 months ago

            I get what you’re saying. Perhaps I just haven’t had too many variables and such that have had such comments. VsCode shows the comments on hover when you’re in other parts of the code base. Which makes most any comment useful because something that is obvious in one part of the code isn’t immediately obvious in another. Though, that necessitates making comments that actually help you figure that out.

    • Ephera@lemmy.ml
      link
      fedilink
      arrow-up
      11
      ·
      edit-2
      6 months ago

      In my opinion, it strongly depends on what you’re coding.

      Low-level code where you need to initialize array indices to represent certain flags? Absolutely comment the living shit out of that. → See response.
      High-level code where you’re just plumbing different libraries? Hell no, the code is just as easily readable as a comment.

      I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:

      • Rather than typing out the specification, write a unit/integration test.
      • Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
      • Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
      • Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.

      The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.

      This does not mean you should avoid comments like they’re actively bad. As many others said, particularly the “why” is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
      But it is still a good idea, when you feel the need to leave a comment that explains something else than the “why”, to consider for a moment, if there’s not some code improvement you should be doing instead.

      • Miaou@jlai.lu
        link
        fedilink
        arrow-up
        4
        ·
        6 months ago

        Hard disagree on your first point. Name the flags with descriptive name, move this initialisation to a function, and there you go, self-documented and clear code.

        • AdNecrias@lemmy.pt
          link
          fedilink
          arrow-up
          3
          ·
          6 months ago

          I’m with you but sometimes you don’t have the chance in low level. Max you can do is create local variables just so the bits you’re XORing are more obvious. And whenever you’re working with something where that’d be wasteful and the compiler doesn’t rid if it, you’re better off with comments (which you need to maintain, ugh)

        • Ephera@lemmy.ml
          link
          fedilink
          arrow-up
          2
          ·
          6 months ago

          Hmm, maybe my opinion is just shit in that regard. I don’t code terribly much low-level, so I’m probably overestimating the complexity and underestimating the options for cleaning things up.
          That was kind of just a random example, I felt like there were many more cases where low-level code is complex, but I’m probably basing this off of shitty low-level code and forgetting that shitty high-level code isn’t exactly a rarity either.

    • AdNecrias@lemmy.pt
      link
      fedilink
      arrow-up
      10
      ·
      6 months ago

      Good code is self documenting as in you don’t need to describe what it is doing and it is clear to read. Whoever says that and isn’t just repeating what they heard understands that whenever you are doing something not explicit in the code it should be on a comment.

      Workarounds and explaining you need to use this structure instead of another for some reason are clear examples, but business hints are another useful comment. Or sectioning the process (though I prefer descriptive private functions or pragma regions for that).

      It also addresses the hint that the code should be readable because you’re not going to have comments to explain spaghetti. Just a hint, doesn’t prevent it. Others also said it, comments are easier to get outdated as you don’t have the compiler to assist. And outdated comments lead to confusion.

    • perviouslyiner@lemmy.world
      link
      fedilink
      arrow-up
      9
      ·
      edit-2
      6 months ago

      What they mean is that the variable names and function names are documentation.

      For example changing “for( i in getList() )” to “for( patient in getTodaysAppointments() )” is giving the reader more information that might negate the need for a comment.

    • Daxtron2@startrek.website
      link
      fedilink
      arrow-up
      9
      ·
      6 months ago

      Its definitely a balance. Good code shouldn’t need much commenting, but sometimes you have to do something for a reason that isn’t immediately obvious and that’s when comments are most useful. If you’re just explaining what a snippet does instead of why you’re doing it that way, there’s probably more work to be done.

    • ඞmir@lemmy.ml
      link
      fedilink
      arrow-up
      8
      ·
      6 months ago

      Code is not self documenting when decision trees are created based on some methodology that’s not extremely obvious

    • Dropkick3038@programming.dev
      link
      fedilink
      arrow-up
      7
      ·
      edit-2
      6 months ago

      I actually agree that “good enough” code can be self-documenting, but it isn’t always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that… In general, I treat comments as a sort of footnote, to provide additional context where helpful.

      There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.

    • humbletightband@lemmy.dbzer0.com
      link
      fedilink
      arrow-up
      7
      ·
      6 months ago

      I follow these simple rules and encourage my colleagues to do so

      1. If I’m just shuffling jsons, then yes, the code should be self documented. If it’s not, the code should be rewritten.

      2. If I implement some complex logic or algorithm, then the documentation should be written both to tests and in the code. Tests should be as dull as possible.

      3. If I write multithreading, the start, interruption, end, and shared variables should be clearly indicated by all means that I have: comment, documentation, code clearness. Tests should be repeated and waits should not be over 50ms.

    • Andromxda 🇺🇦🇵🇸🇹🇼@lemmy.dbzer0.comOP
      link
      fedilink
      English
      arrow-up
      6
      ·
      6 months ago

      I absolutely agree, and I too hate this stupid idea of “good code documenting itself” and “comments being unnecessary”.
      I have a theory where this comes from. It was probably some manager, who has never written a single line of code, who thought that comments were a waste of time, and employees should instead focus on writing code. By telling them that “good code documents itself”, they could also just put the blame on their employees.
      “Either you don’t need comments or your code sucks because it’s not self-documenting”
      Managers are dumb, and they will never realize that spending a bit of time on writing useful comments may later actually save countless hours, when the project is taken over by a different team, or the people who initially created it, don’t work at the company anymore.

      • ChickenLadyLovesLife@lemmy.world
        link
        fedilink
        English
        arrow-up
        6
        ·
        6 months ago

        I’ve never had a manager that was even aware of the comments vs. no comments issue. If I ever had, I would have just told them that a lack of comments makes the original coder harder to replace.

    • englislanguage@lemmy.sdf.org
      link
      fedilink
      arrow-up
      3
      arrow-down
      2
      ·
      6 months ago

      I have worked on larger older projects. The more comments you have, the larger the chance that code and comment diverge. Often, code is being changed/adapted/fixed, but the comments are not. If you read the comments then, your understanding of what the code does or should do gets wrong, leading you on a wrong path. This is why I prefer to have rather less comments. Most of the code is self a explanatory, if you properly name your variables, functions and whatever else you are working with.

    • englislanguage@lemmy.sdf.org
      link
      fedilink
      arrow-up
      1
      ·
      6 months ago

      One example for self documenting code is typing. If you use a language which enforces (or at least allows, as in Python 3.8+) strong typing and you use types pro actively, this is better than documentation, because it can be read and worked with by the compiler or interpreter. In contrast to documenting types, the compiler (or interpreter) will enforce that code meaning and type specification will not diverge. This includes explicitly marking parameters/arguments and return types as optional if they are.

      I think no reasonable software developer should work without enforced type safety unless working with pure assembler languages. Any (higher) language which does not allow enforcing strong typing is terrible.