• Honytawk@lemmy.zip
    link
    fedilink
    arrow-up
    187
    ·
    4 months ago

    Same with BIOS descriptions.

    FGTSAB switch [toggles the FGTSAB setting]

    infuriating

          • jaybone@lemmy.world
            link
            fedilink
            arrow-up
            1
            arrow-down
            1
            ·
            4 months ago

            And who updates that documentation three months later when a bug gets fixed or a new requirement get implemented?

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

              The person who changed the code, it’s just ordinary maintenance. The comments may not execute, but I submit they are as much a part of the program as the executable code. Maybe over time those comments are condensed, or even removed; no different than any other refactoring or cleanup.

    • BenLeMan@lemmy.world
      link
      fedilink
      arrow-up
      12
      ·
      4 months ago

      Yup, my first thought as well. While those days are thankfully over, those braindead BIOS “help” messages remain etched into my mind forever.

      • RogueBanana@lemmy.zip
        link
        fedilink
        English
        arrow-up
        4
        ·
        4 months ago

        Are the recent ones any better? I got a gigabyte b660m for 12th gen intel and it’s really bad at that. Had to look up a lot to figure out things.

        • BenLeMan@lemmy.world
          link
          fedilink
          arrow-up
          2
          ·
          4 months ago

          Maybe it’s an ASUS thing but both my current and previous boards have been pretty good with the help texts.

          • Honytawk@lemmy.zip
            link
            fedilink
            arrow-up
            1
            ·
            edit-2
            4 months ago

            Snapmaker Luban is amazing with its help messages.

            Every setting in this 3D slicer is completely explained how the setting works, what the different options are, with pictures and even what every option is the most optimal in whatever situation.

            Too bad that it isn’t the best program unless you have a Snapmaker, and even then…

    • ඞmir@lemmy.ml
      link
      fedilink
      arrow-up
      3
      ·
      4 months ago

      Love having to enable “support for sleep state 5” to turn off USB power when the PC is off

  • SlopppyEngineer@lemmy.world
    link
    fedilink
    arrow-up
    101
    ·
    4 months ago

    Best comment ever was “It used to work like this but person at client demanded it work like that on this date” when the client complained it shouldn’t work like that.

    • conciselyverbose@sh.itjust.works
      link
      fedilink
      arrow-up
      107
      ·
      4 months ago

      That’s basically what comments are most useful for. When you’re doing something that’s not obvious, and want to make sure the “why” doesn’t get lost to time.

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

        I spent a year making my company’s iOS apps accessible (meaning usable for the blind and people with vision disabilities). I had to do a lot of weird shit either because of bugs in Apple’s VoiceOver technology or because of the strange way in which our code base was broken up into modules (some of which I did not have access to) and I would always put in comments explaining why I was doing what I was doing. The guy doing code review and merges would always just remove my comments (without any other changes) because he felt that not only were comments unnecessary but also they were a “code smell” indicating professional incompetence. I feel sorry for whoever had to deal with that stuff at a later point.

        • lad@programming.dev
          link
          fedilink
          English
          arrow-up
          1
          ·
          4 months ago

          Well, this is shitty

          I hope the reviewer did not also squash commits, and the next programmer would be able to at least dig what was there.

          Doing changes after some rockstar dev implemented some really complex service, but left no clues as to what does what is so frustrating, and I can never be sure that I don’t break anything in a different place completely

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

            I meant to say commits and not merges, and yes he removed the comments before committing. It made no difference in long run because every new release broke all the accessibility stuff anyway. It’s amazing how little developers can be made to care about blind people - almost as little as managers. The only reason my company cared at all was they were facing million-dollar-a-month fines from the FCC.

    • Trailblazing Braille Taser@lemmy.dbzer0.com
      link
      fedilink
      arrow-up
      55
      arrow-down
      1
      ·
      4 months ago

      The best comments are “why” comments, the runner up is “how” comments if high-level enough, and maybe just don’t write “what” comments at all because everyone reading your code knows how to read code.

    • jaybone@lemmy.world
      link
      fedilink
      arrow-up
      9
      ·
      4 months ago

      That’s actually the perfect comment, because if anyone ever comes back to fuck with you about it, it’s explained right there. Then you turn it right back around on management and watch them run around like chickens with their heads cut off.

      • lad@programming.dev
        link
        fedilink
        English
        arrow-up
        1
        ·
        4 months ago

        Out management used to tell us, that even if head of department had committed to doing something some way, there’s no way or need to hold them accountable. It’s just that situation has changed, and nobody should bat an eye.

        To be fair, they also did not pressure us much for the missed deadlines or missing features, because it was indeed the result of the situation described in the first paragraph

  • yetAnotherUser@discuss.tchncs.de
    link
    fedilink
    arrow-up
    92
    arrow-down
    1
    ·
    4 months ago
    /*
     * Gets stupidFuckingInteger
     *
     * @returns stupidFuckingInteger
    */
    public double getStupidFuckingInteger() {
        return stupidFuckingInteger;
    }
    
    
  • ImpulseDrive42@lemmy.world
    link
    fedilink
    arrow-up
    54
    arrow-down
    4
    ·
    4 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.

    • Vigge93@lemmy.world
      link
      fedilink
      arrow-up
      21
      ·
      edit-2
      4 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
        ·
        4 months ago

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

        • Vigge93@lemmy.world
          link
          fedilink
          arrow-up
          1
          ·
          4 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
      11
      ·
      4 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
      ·
      4 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
          ·
          4 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
            2
            ·
            4 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
      10
      ·
      edit-2
      4 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.

    • perviouslyiner@lemmy.world
      link
      fedilink
      arrow-up
      8
      ·
      edit-2
      4 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
      8
      ·
      4 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.

    • humbletightband@lemmy.dbzer0.com
      link
      fedilink
      arrow-up
      7
      ·
      4 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.

    • Dropkick3038@programming.dev
      link
      fedilink
      arrow-up
      6
      ·
      edit-2
      4 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.

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

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

    • Andromxda 🇺🇦🇵🇸🇹🇼@lemmy.dbzer0.comOP
      link
      fedilink
      English
      arrow-up
      5
      ·
      4 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
        5
        ·
        4 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
      1
      ·
      4 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.

    • englislanguage@lemmy.sdf.org
      link
      fedilink
      arrow-up
      3
      arrow-down
      2
      ·
      4 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.

  • nikaaa@lemmy.world
    link
    fedilink
    arrow-up
    25
    arrow-down
    10
    ·
    4 months ago

    Good code is self-explanatory. You should only comment your code if it does something unexpectedly complicated.

    That being said, it’s always a good idea to write a manual, about how to use the code. Don’t document how it works, because those who can code will understand it anyways, and those who can’t, have no need to understand it.

    • BorgDrone@lemmy.one
      link
      fedilink
      arrow-up
      28
      ·
      4 months ago

      Good code is self-explanatory. You should only comment your code if it does something unexpectedly complicated.

      The code shows what is being done. The comments should explain the why.

      • Pasta Dental@sh.itjust.works
        link
        fedilink
        arrow-up
        11
        ·
        edit-2
        4 months ago

        Yes. This 1000x. I hate it at work when I come across code that was written 3 years ago that has literally no traces of why it’s there and a quick summary of what it does. Especially because that code is always the most abbreviated spaghetti you’ve ever seen. People should stop thinking (their) code documents itself because 99.999% of programmers cannot do it right.

        I really like the Google way of coding: assume the person reading the code is the most 1337 programmer ever, BUT that this person knows absolutely nothing about the project

        • BorgDrone@lemmy.one
          link
          fedilink
          arrow-up
          4
          ·
          4 months ago

          Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

    • potustheplant@feddit.nl
      link
      fedilink
      arrow-up
      11
      arrow-down
      1
      ·
      4 months ago

      Hard disagree. It’s a lot easier and faster to understand a function that is prefaced with a small line of text explaining what it does rather than trying to figure it out yourself.

      It’s not about whether you can understand the code or not, it’s about efficiency and clarity.

      • Aurelius@lemmy.world
        link
        fedilink
        arrow-up
        6
        ·
        4 months ago

        Yeah, just 15 seconds and jot down a comment. Whenever I’m even hesitant, I just leave a comment. Doesn’t hurt anything and it can always be removed if not needed

        Easier to remove later rather than add it after the fact

      • Aux@lemmy.world
        link
        fedilink
        arrow-up
        4
        arrow-down
        5
        ·
        4 months ago

        Hard disagree - that’s just dumb:

        // Calculates tax
        function calculateTax() { }
        
        • uis@lemm.ee
          link
          fedilink
          arrow-up
          11
          arrow-down
          1
          ·
          edit-2
          4 months ago

          Hard disagree - that’s very helpful:

          // Calculates Personal Income Tax by formula from section 1.2.3 of tax code. Other taxes like VAT are not calculated.
          function calculateTax() { }
          
          • Aux@lemmy.world
            link
            fedilink
            arrow-up
            1
            arrow-down
            5
            ·
            4 months ago

            If it calculates personal income tax, just call calculatePersonalIncomeTax.

              • usernamefactory@lemmy.ca
                link
                fedilink
                arrow-up
                3
                ·
                4 months ago

                I’m a new developer. Is that referring to page 123 of the in-house documentation? Version 12.3 of the code? I have no clue.

                You’d have to call it something like calculatePersonalIncomeTaxPerTaxCodeSection1_2_3, but I get exhausted just looking at that. There comes a point where the cognitive work of reading crazy long camel case names is more trouble than it’s worth.

                An explanation of what specification a function was written to implement is a perfectly appropriate comment. Could be improved by a direct link where possible. But it’s worth noting what that comment isn’t doing - specifying any implementation details. For that, I really can just read the code.

      • weststadtgesicht@discuss.tchncs.de
        link
        fedilink
        arrow-up
        2
        arrow-down
        4
        ·
        4 months ago

        If done right, the “what it does” is in the method name. If your method is too complicated to summarize in its name, chances are good you should split it up or extract parts of it.

    • TORFdot0@lemmy.world
      link
      fedilink
      English
      arrow-up
      2
      ·
      4 months ago

      This is true, but it’s easier and faster to parse plain English and so if I don’t adequately comment my code the first time. I will be commenting it when I have to return to it for whatever reason. Honestly the second round of commenting is more verbose and clearer than the function x does y style of comments I tend to make when coding the first time

  • zerofk@lemm.ee
    link
    fedilink
    arrow-up
    3
    ·
    edit-2
    4 months ago

    Our code base is filled with “//constructor”, “//destructor”, “//assignment”, or the ever enlightening “Foo GetFoo(); // GetFoo”.

    This is not what they mean by self-documenting code.

  • Maalus@lemmy.world
    link
    fedilink
    arrow-up
    15
    arrow-down
    13
    ·
    4 months ago

    How bad programmers comment their code. Good programmers don’t comment at all and let the code speak for itself, leaving commenting to some obscure and arcane implementation the coder left in after a week long binge on caffeine and gummy bears.

    • BombOmOm@lemmy.world
      link
      fedilink
      English
      arrow-up
      11
      ·
      edit-2
      4 months ago

      Code should absolutely speak for itself. But the occasional comment is still good to explain the ‘why’ of the code when the why isn’t very obvious, often due to a niche requirement. Also any time you have to break out a hack, that needs comments up the ass, what was the bug, what URL did you find the fix at, why does this hack work, etc etc. It’s very satisfying to go back and remove those hacks after they are no longer needed, often because the underlying technology fixed the bug that had to be hacked around.

      • NotMyOldRedditName@lemmy.world
        link
        fedilink
        arrow-up
        3
        arrow-down
        1
        ·
        edit-2
        4 months ago

        It definitely feels great when I get to remove the

        //hack abc due to bug in library xyz version 1.4.5, issue tracker says it’s fixed in 1.5.0. - link

  • ClassifiedPancake@discuss.tchncs.de
    link
    fedilink
    arrow-up
    1
    ·
    4 months ago

    At work we let Typescript and descriptive naming document our code. Only when something is a workaround or otherwise weird will we add comments. So far it has worked great for us.

  • KillingTimeItself@lemmy.dbzer0.com
    link
    fedilink
    English
    arrow-up
    2
    arrow-down
    12
    ·
    edit-2
    4 months ago

    this is why i very rarely comment with descriptive comments. If you’re reading my code and don’t understand what it is, even with how shit it is, you have no business reading whatever fucking crackpot shit im writing.

        • potustheplant@feddit.nl
          link
          fedilink
          arrow-up
          2
          ·
          4 months ago

          Doesn’t matter. Even if it’s your code, you might revisit something you made months or a year after doing it and having comments will speed up your work. It’s a very basic good practice.

          • KillingTimeItself@lemmy.dbzer0.com
            link
            fedilink
            English
            arrow-up
            1
            arrow-down
            1
            ·
            4 months ago

            i do have comments, for some things, but there are a lot of “commenting” standards that are just shit. I find i don’t care what the actual piece of code is doing, i care more about it’s place in the rest of the code, and i’d much rather have “anti comments” instead.