• fidodo@lemm.ee
      link
      fedilink
      arrow-up
      45
      arrow-down
      1
      ·
      1 year ago

      Why was this written like this? It makes no sense. I'll git blame it and ask them what's going on. Oh it's me…

    • Rhaedas@kbin.social
      link
      fedilink
      arrow-up
      12
      ·
      1 year ago

      There's no question I wrote the couple of things I've done for work to automate things, but I swear every time I have to revisit the code after a long while it's all new again, often wondering what the hell was I thinking. I like to tell myself that since I'm improving the code each time I review it, each new change must be better overall code. Ha. But it works…

    • ProfessorPuzzleCode@lemmy.world
      link
      fedilink
      arrow-up
      9
      ·
      1 year ago

      I stated programming games on a school computer in the early to mid 80's. When the tape drive broke, I still used to have the code in my head, just type it all in for others to play. Now I find code I wrote last month and can't remember doing it. At least it tends to be, "which genius wrote this" these day. Tend to leave comments everywhere for myself now, including my own name and other messages to myself like,"don't touch this it works, your bug will be in…"

      • Aceticon@lemmy.world
        link
        fedilink
        arrow-up
        7
        ·
        edit-2
        1 year ago

        Yeah, I'm about the same age and started noticing my ability to keep everything in memory falling at around the mid 20s. I mean, I'm still probably way better at keeping all manner of obscure details in memory compared to the average person (we exercise that so much in this profession it's only normal), but it's below the peak point, not enormously so but it's kind like having once been a top "athlete", years later you know you can't reach that peak performance anymore.

        Also once you go through the full life-cycle of enough of your projects (that got shipped and a year or two later you have to pick it up and change it), you kinda figure out that even at peak "performance" you wouldn't be remembering much from a project from years ago and start adding comments to help you pick it back up and alert you to possible pitfalls you noticed and avoided but forgot all about in the meanwhile.

        Fortunally I figured it out long ago that I've created a couple of principles around commenting that have repeatedly saved my ass years later: things like documention parameter assumptions in functions, actually writting down the "why we do this" or commenting before the code of especially complex algorithms (I actually design the algorithm to the comment first and only after than code it).

        • pingveno@lemmy.ml
          link
          fedilink
          arrow-up
          2
          ·
          1 year ago

          I started a practice with my team on our wiki. We have a section named the Oamonomicon, since out system is named OAM. Any sort of weird one off request or problem gets documented there. What were the symptoms? What steps did we use to find the problem? Then if we start seeing a pattern of issues, we have a better idea of how to resolve them.

          • Picard@nrw.social
            link
            fedilink
            arrow-up
            1
            ·
            1 year ago

            @ProfessorPuzzleCode @Aceticon

            Oh ruck. At twenty I could remember the direct way through the Zac Mc.Kracken Mazes. And all the chords of our Bands songs. And all the Beatles lyrics. But heck… no code… now I at least remember the bash scripts…

    • Dandroid@dandroid.app
      link
      fedilink
      arrow-up
      3
      ·
      1 year ago

      Maybe I just haven't worked at a company long enough for this to happen, but I tend to remember what I previously worked on very well. I am still disgusted by the code I wrote sometimes. But that just means I'm learning and getting better at coding.

      • Potatos_are_not_friends@lemmy.world
        link
        fedilink
        arrow-up
        5
        ·
        1 year ago

        When I was a team lead, I was juggling 4 things every day.

        Meetings, help a junior, PR a critical system, code a thing.

        Repeat every day and after a month, I wouldn't remember what I worked on the prior month.

        • Dandroid@dandroid.app
          link
          fedilink
          arrow-up
          2
          ·
          1 year ago

          Yeah, I guess that's fair. I was a team lead for only like 2 weeks before my project was canceled, and yeah, I remember it being similar. I'm not sure I wrote a single line of code during those 2 weeks, though. I was too busy. Or maybe I did and I don't remember, but since the project was canceled, it never came back to haunt me.

    • Rob@lemmy.world
      link
      fedilink
      English
      arrow-up
      1
      ·
      1 year ago

      Me too. But the other day, a junior developer and I were looking at some fairly old code, and I recognized the writing style in the comment as mine. We ran p4 annotate and, sure enough, I was the baddie.

  • datendefekt@lemmy.ml
    link
    fedilink
    arrow-up
    84
    ·
    1 year ago

    I had so many arguments with my team lead. He thought comments were an antipattern because that meant the code wasn't expressive enough.

    I understood where he was coming from, but a little hint here and there why the fuck the code is doing what it's doing would've been nice.

    • ebc@lemmy.ca
      link
      fedilink
      arrow-up
      58
      arrow-down
      2
      ·
      1 year ago

      Yeah, good code should explain the "what" without the need for comments. Good comments explain the "why".

      • SolarMech@slrpnk.net
        link
        fedilink
        arrow-up
        16
        ·
        1 year ago

        Generally, you can replace some comments with variable names or comment names. Which means you must already be in the habbit of extracting methods, setting new variables to use appropriate names, and limit context to reduce the name (Smaller classes and methods means shorter names can be just as expressive, because the context is clearer). It lowers the number of wtfs per minute you get reading code before you even need whole sentences to explain why things are done in a certain way, because the names can be a powerful hint.

        But realistically, you end up needing comments for some things anyways.

      • pomodoro_longbreak@sh.itjust.works
        link
        fedilink
        arrow-up
        10
        ·
        1 year ago

        Also some parts of code are just going to smell, because of deadlines, other trade offs. For those it helps to have a comment to really highlight that bit of weirdness - the what and the why. If it is weird it should really "pop out" when you're reading it.

      • Aceticon@lemmy.world
        link
        fedilink
        arrow-up
        3
        ·
        edit-2
        1 year ago

        It's a bit more complex than that.

        On one side you should put comments on the choices of how to do certain things at a code level that are the product of external limitations or requirements (over the years I've seen quite a lot of code which was kept doing things in a certain way and turned out the actual reason for it had long stopped being applicable) whilst most of the code should indeed be done to be self explanatory (though complex algorithms, especially if optimized or relying on obscure functionality, should probably be preceeded by a summary).

        However, go up one level to software design and suddenly comments become more important (at the function and class level). They document functionality for significant chunks of code (so make it way faster for people trying to figure out the design of a code base they never saw before, as otherwise they would need to wade through a lot of code) as well as implied expectations in things like parameters or return values (i.e. that a variable is never expected to be null, that a zero size string is treated as NO DATA and so on) of functionality meant to be called from the outside (a kind of comment which is really just a lightweight form of an Interface Requirements Specification document). Mind you, over the years I've seen tons of comments documenting functions "just because" and without understanding what's the point of doing it (probably because the programmers were told the HAD to do it) in the libraries and frameworks from some of the biggest companies around.

        You could say the WHY of commenting is also important.

        • SocialMediaRefugee@lemmy.ml
          link
          fedilink
          arrow-up
          2
          ·
          edit-2
          1 year ago

          Yes, two of the most important things I see comments do is explain things like boundary conditions, "This is why we stop at 50 here." and historical reasons "We have to return a 1 here because we still use calling func FOO for all of our calls still and it expects 1 as the default…"

          Another helpful use is to describe the expected format of the input. "We expect a struct with this format here…" Stick in a small example too. It makes it so much easier to quickly scan the code's flow.

      • magic_lobster_party@kbin.social
        link
        fedilink
        arrow-up
        2
        arrow-down
        2
        ·
        1 year ago

        Often you can find the “why” in the file’s Git history. If done properly, you should be able to find which commit introduced this change, and which issue is attached to this commit.

    • SokathHisEyesOpen@lemmy.ml
      link
      fedilink
      English
      arrow-up
      46
      ·
      1 year ago

      I used to work with a guy who insisted his code was self explanatory, and then he'd nest loops 5 levels deep and give variables names like "thingyOne".

        • CanadaPlus@lemmy.sdf.org
          link
          fedilink
          arrow-up
          10
          ·
          1 year ago

          Namely, the first one. Next you're going to ask about thingySixtyNine or thingyOneHundredTwentyTwo, I suppose?

          • dankm@lemmy.ca
            link
            fedilink
            English
            arrow-up
            1
            ·
            edit-2
            1 year ago

            I wonder if there's a warning for that in Clang or GCC. That seems like something I'd want, but also want it to be 100% opt-in. Not even enabled with -Wall or -Wextra.

      • fred@lemmy.ml
        link
        fedilink
        arrow-up
        9
        ·
        1 year ago

        That guy wasn't in charge, I hope? That would not have passed code review with me at least.

      • SocialMediaRefugee@lemmy.ml
        link
        fedilink
        arrow-up
        3
        ·
        1 year ago

        I worked with a guy who was smart but “useless smart”. He was convinced that “code is self descriptive”, that is comments are not needed because the code speaks for itself. Well that is like saying DNA is self descriptive. Yes, I can sit there tracing the code, tracking the variables, etc or you could make a small effort to describe what is happening instead and save me a lot of time and risk missing subtle points.

    • Punkie@lemmy.world
      link
      fedilink
      arrow-up
      23
      ·
      1 year ago

      I had a boss who hated comments because he wanted "clean code," and that comments means you aren't using the wiki. The build approval process actually stripped out all comments via a script.

      Then we lost the wiki.

      • palordrolap@kbin.social
        link
        fedilink
        arrow-up
        3
        ·
        1 year ago

        For my own amusement I'm going to pretend you were using something like Perl where determining what's a comment and what's code can be context sensitive.

        i.e. stripping from # to the end of the line can be a very wrong thing to do in a language where the comment marker can actually be used in other niche ways.

        Strip the wrong "comment" and your code won't compile. Or worse, do something unexpected.

    • CanadaPlus@lemmy.sdf.org
      link
      fedilink
      arrow-up
      8
      arrow-down
      1
      ·
      1 year ago

      It kind of feels like engineers look for simple solutions to what are ultimately complicated psychological questions sometimes.

    • Alien Nathan Edward@lemm.ee
      link
      fedilink
      arrow-up
      1
      ·
      1 year ago

      I agree with your team lead wholeheartedly, but not for the reasons he would tell you. Comments should be used when code is too complex for the "name your variables nouns and your methods verbs" convention doesn't communicate what the code does in a narrative fashion. Thing is, that level of complexity is definitely a code smell. You seem to be saying that clarifying comments are the solution, he seems to think that you should be able to rename vars and methods until the meaning is clear, and Im offering a third way: figure out why the fuck the code is doing something hard to understand and maybe try to unfuck it, then resort to comments if and only if that's not possible. Remember that a code smell isn't necessarily something that needs to be removed, it's just a flag that says "let's make double damn sure there isn't a better way to do this before we do it this way".

      • SocialMediaRefugee@lemmy.ml
        link
        fedilink
        arrow-up
        4
        ·
        1 year ago

        Yes, you don't need to comment "n++" to say it is incrementing it but you should mention why you are starting with 1 instead of 0, etc. Boundary conditions are notoriously tricky and need to be documented. Then there are historical reasons that are NEVER obvious, "This function has to return -2 as a default because we've been calling it using X for years and it expects a -1 as the error…"

        • Alien Nathan Edward@lemm.ee
          link
          fedilink
          arrow-up
          1
          ·
          edit-2
          1 year ago

          this function returns -2 as success and -1 as error

          Thats exactly the kind of thing I'm talking about when I say to prioritize refactoring over comments. If you own the system returning the error code, drag it out of the 1970s and have it return an error object with some actual information in it instead. If you don't own the system, wrap the error code in an enum that adds syntactic meaning or do a map of integer and exception and then return the mapped exception. The very last resort, after you've tried everything else, should be

          return -1; //-1 indicates success

          • SocialMediaRefugee@lemmy.ml
            link
            fedilink
            arrow-up
            1
            ·
            1 year ago

            I've worked on satellite command and control software that is literally using a 1970s OS. The code is limited for historical reasons and you have to work with the structure you are given.

            • Alien Nathan Edward@lemm.ee
              link
              fedilink
              arrow-up
              1
              ·
              1 year ago

              okay. doesn't mean you still shouldn't refactor or add a layer of abstraction where you can. we're looking for a generalizable principle here and generalizable principles don't assume that you're working with satellites that are older than the dev.

    • kaput@jlai.lu
      link
      fedilink
      arrow-up
      5
      arrow-down
      5
      ·
      1 year ago

      Let me Guess, There is no added value in comments. Customer dont want to pay for comments, only for code that adds value.

    • WindowsEnjoyer@sh.itjust.works
      link
      fedilink
      arrow-up
      3
      arrow-down
      5
      ·
      1 year ago

      Sometimes I just leave "feed it back to ChatGPT and ask to explain" sort of things xD.

      This might not sound logical, but when you are writing Ansible for something that has no module or very complex - mix of Jinja2 templates and yaml tasks makes it superb hard, especially if you are looking for the first time.

      Seriously, comments are useful, especially in top of the function.

  • peopleproblems@lemmy.world
    link
    fedilink
    arrow-up
    63
    arrow-down
    1
    ·
    1 year ago

    I am working with an in-house "rapid development team." They have rigorous intake, story and task break down, scheduling of sprints, QA, definition of done, integration test coverage, E2E and min 90% unit test coverage etc. etc.

    They have a strict policy of "no code comments, self documenting code only." They will go in and remove comments that my DevOps team puts in there, because it screws up that policy.

    Luckily, we adopted the policy of having local branches with these comments in place. Once they move beyond the project, we're putting them in.

    • AA5B@lemmy.world
      link
      fedilink
      arrow-up
      25
      arrow-down
      1
      ·
      edit-2
      1 year ago

      They do have a point though. When we’ve gone through phases where the industry focuses on commenting code and other documentation, most of it is useless.

      Code comments should have a reason, and are no substitute for readable code.

      However you’re also right though that people jump onto “all or nothing”. I recently did a code Review that I held up for comments. In this case, they were doing something very atypical to get around a limitation so it was a clear case of comments needed. The next person through will say “what is this shit?” And “fix” it, without knowing there was a good reason

      • buzziebee@lemmy.world
        link
        fedilink
        arrow-up
        13
        ·
        edit-2
        1 year ago

        Yeah "why" comments are absolutely fine, "what" comments are useless at best and can be harmful at worst.

        I feel like this constant flood of "write comments" posts are from CS students who are told to comment everything by their lecturers. Descriptive variable and function names help explain the "what" of code pretty well most of the time.

        Sure with some old languages like C89 where you are limited in your variable name length you probably do need comments to explain wtf is going on, but most code bases aren't as constrained.

        • _stranger_@lemmy.world
          link
          fedilink
          arrow-up
          9
          ·
          edit-2
          1 year ago

          I have this argument with other devs all the time.

          Hey, you know this 200 line nested if statement that suddenly returns in the middle of the condition is "7"? Yeah, that needs a refactor or at least a fucking comment.

          I get a pull request that adds a log line that reads something like "special case 7 triggered.".

      • DrQuint@lemm.ee
        link
        fedilink
        arrow-up
        8
        arrow-down
        1
        ·
        1 year ago

        Having no comments doesn't force code to be self-documenting. I understand the cult of code extremist, but No-Commenters are just WEAK and PATHETIC wannabes trying to immitate the true, functional extremists, such as the 16-Space-Tabbers

    • hoodle@programming.dev
      link
      fedilink
      arrow-up
      12
      ·
      1 year ago

      That's silly. I've never seen comments even as a way to explain what your code is doing (the code often does do that anyway). It's important to say WHY you're doing it the way you are.

      That way anyone else who comes in there can have the same context you did when you implemented it, which imo is where most bugs occur. People don't realize what assumptions you made when it was first written, and then make their own (which can easily clash).

    • Aceticon@lemmy.world
      link
      fedilink
      arrow-up
      5
      ·
      1 year ago

      I just love it when people who have no understanding of the purposes, objectives and applicability of various parts of a famous software development process and just follow it in a blind fashion-following way.

      And by "love it" I mean "get frustrated to no end even though by now I should know better".

    • Longpork_afficianado@lemmy.nz
      link
      fedilink
      arrow-up
      4
      ·
      1 year ago

      for i in array_sometimes_we_get_ints_from_upstream_functions_and_need_to_convert_them_to_floats_or_downstream_functions_throw_exceptions: out_array.append(float(i)

  • psycho_driver@lemmy.world
    link
    fedilink
    arrow-up
    58
    ·
    1 year ago

    My favorite part is looking at my ancient code and thinking "Holy hell I don't remember being that smart. What happened?"

    • kevincox@lemmy.ml
      link
      fedilink
      arrow-up
      31
      ·
      1 year ago

      Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?

      Brian Kernighan - The Elements of Programming Style, 2nd edition, chapter 2

    • rob64@startrek.website
      link
      fedilink
      arrow-up
      11
      ·
      1 year ago

      A similar phenomenon is knowing you're going to need to go back and update some older section of code and when you finally get around to it, it turns out you wrote it that way to begin with. It's like… I didn't think I knew about this approach before…

    • Punkie@lemmy.world
      link
      fedilink
      arrow-up
      5
      arrow-down
      1
      ·
      1 year ago

      This right here. Plus stuff like "this is the functions section" and "this is the main script" helps make shell scripts more readable because functions have to come first, and if you just want to get to the main point, you can skip the functions section.

  • gens@programming.dev
    link
    fedilink
    arrow-up
    45
    arrow-down
    1
    ·
    1 year ago

    I'd like all files to have a big comment on top that says wtf this is, why is it, and roughly how it works. Bonus for ascii art.

    • marcos@lemmy.world
      link
      fedilink
      arrow-up
      1
      ·
      1 year ago

      It's a safe bet that anybody trying that jump over it, through the rails routine is a junior.

  • Spzi@lemm.ee
    link
    fedilink
    English
    arrow-up
    19
    ·
    1 year ago

    The obvious solution is to abandon your project not too late; leave on a high note.

    I also found it very useful to document every step of my setup procedures, right after I figured out what works. At least the respective CL.

    • el_abuelo@lemmy.ml
      link
      fedilink
      arrow-up
      4
      ·
      1 year ago

      It is well known that as soon as you document a setup procedure, it is out of date and needs redocumenting.

  • RandomVideos@programming.dev
    link
    fedilink
    arrow-up
    16
    ·
    1 year ago

    I have a special skill of writing terrible code, not seeing it for half a year, and then remembering exactly what the code did

  • Alien Nathan Edward@lemm.ee
    link
    fedilink
    arrow-up
    16
    ·
    edit-2
    1 year ago

    `/* Gets CustomerEntity from customer repository by customer ID or throws a customer not found exception */

    public CustomerEntity getCustomerEntityById(String customerId){ customerRepository.findById(customerId).orElseThrow(new CustomerNotFoundException()) }`

  • nosurprises@lemm.ee
    link
    fedilink
    English
    arrow-up
    23
    arrow-down
    10
    ·
    edit-2
    1 year ago

    Code is the documentation. Any other form of documentation requires additional maintenance and becomes obsolete quickly.

    • EvilMonkeySlayer@kbin.social
      link
      fedilink
      arrow-up
      22
      arrow-down
      3
      ·
      1 year ago

      "Code is the documentation"

      Is the laziest excuse I've come across. Like, not everyone knows everything and complex code exists, it is not hard to put in some text explaining the basics of what something does.

      Like, unless you're dealing with that code everyday it's going to look like double dutch to anyone new coming to it.

      I've had people say that to me before, and it is absolutely infuriating in its laziness and cop out excuse.

      • Fedora@lemmy.haigner.me
        link
        fedilink
        arrow-up
        1
        ·
        1 year ago

        If someone must explain to me what code does in comments, then I think that code is bad.

        Developers invented high-level programming languages for a reason. If someone writes bottom-top, unreadable code with comments, then they might as well write top-bottom, readable code without comments instead. That's what I believe self-documenting code is.

        But if someone explains to me why code does what it does in comments, then that's fine. Essential complexity exists. The point is that that code is readable already, we know what it does, but not why. That's what needs an explanation in comments.

      • nosurprises@lemm.ee
        link
        fedilink
        English
        arrow-up
        1
        arrow-down
        16
        ·
        1 year ago

        You can't read code, can you? You need some simplified text explanation of what it does. And a programming language higher than assembler is already a set of simplified text instructions. Why are you even participating in this discussion?

        • Demonen@lemmy.ml
          link
          fedilink
          arrow-up
          8
          ·
          1 year ago

          The comments are not for what, they are for why.

          The documentation is a summary of the code, a quick guide to the software to more easily find your way to what you need to work with.

          Are you saying that when you work with some random library, you skip their documentation and go directly to the source code? That's absurd. If you do it that way, you're wasting so much time!

          • li10@feddit.uk
            link
            fedilink
            English
            arrow-up
            7
            ·
            1 year ago

            They sound like a great person to work with, “it’s not my fault for lack of documentation, it’s your fault for being an idiot”

    • Vlyn@lemmy.zip
      link
      fedilink
      English
      arrow-up
      12
      ·
      1 year ago

      The code shows what happens. But comments should explain why it was done this way.

      Sometimes the code started simple and readable, till you ran into a weird edge case a year ago. Now the code no longer looks as obvious and another developer might scratch their head when they read over it. A small comment can help out there quite a bit.

      Or you're doing something stupid in code not because you want to, but because management forced you to. So you put a comment there that the code isn't wrong, management wanted that behavior.

      • magic_lobster_party@kbin.social
        link
        fedilink
        arrow-up
        1
        ·
        1 year ago

        The why can usually be found in Git and issue trackers. Just look at the history of the file to get some decent clue about why a piece of code was programmed in a certain way.

        • Vlyn@lemmy.zip
          link
          fedilink
          English
          arrow-up
          2
          ·
          1 year ago

          That works for newer projects, but on older projects there's a dozen commits for any given line and a handful of Jira tickets that have something to do with it, but none that say "Change exactly this". A comment why you made an interesting design decision costs a lot less time than trying to unwrap the commit history… Especially when you can't even find a clue on why this was done as the commit might simply be "Implemented feature XY"

          • magic_lobster_party@kbin.social
            link
            fedilink
            arrow-up
            1
            ·
            edit-2
            1 year ago

            I think comments should be a last resort when all other methods are inadequate. Proper git commit logs have helped me many times to understand why a certain thing is needed.

            Git logs don’t need maintenance either. They always tell what was true when the code was written. Comments need maintenance, and are often difficult to keep updated.

            You can write a detailed comment about the whys of a particular function, only for it to become outdated in weeks when the functionality has changed.

            • Vlyn@lemmy.zip
              link
              fedilink
              English
              arrow-up
              2
              ·
              1 year ago

              I still haven't found a proper command or tool to do a multi-commit git blame.

              Like I want to know who changed the logic in this line. But the last commit was a format refactor. And the commit before that just changed a tiny detail. So now I'm digging through the entire file history just to find the spot where this one line was introduced or actually changed.

              If you have any tips for that, I'm all ears.

              • magic_lobster_party@kbin.social
                link
                fedilink
                arrow-up
                1
                ·
                1 year ago

                I usually use the GUI in IntelliJ for those kind of purposes, but any other GUI might do. Then I perform a manual binary search to find the commit I want.

    • saltesc@lemmy.world
      link
      fedilink
      arrow-up
      10
      arrow-down
      1
      ·
      edit-2
      1 year ago

      Ah, I see you don't optimise enough.

      It should be…

      Past you "I've shed so many lines and boosted processing time. It's a masterpiece. I should document this for future me because it's complex as hell."

      Future you "What. The. Hell…" five minutes later "Oh, I see. I'm a fucking narcissist trying to be god of something 10 people run once a week."

      • magic_lobster_party@kbin.social
        link
        fedilink
        arrow-up
        2
        arrow-down
        1
        ·
        1 year ago

        No. Just give the function a good descriptive name with good descriptive parameters. Keep the function simple too. If you can’t, try to refactor and see if that helps.

        If you are still unable to express yourself via code, then you should use comments to guide the reader.

        • auchschonda@feddit.de
          link
          fedilink
          arrow-up
          2
          ·
          edit-2
          1 year ago

          What about exceptions raised within the function? Will you also put them in the descriptive function name? ;)

              • magic_lobster_party@kbin.social
                link
                fedilink
                arrow-up
                1
                ·
                1 year ago

                According to who? If I have access to the source code, which I often do, I’d rather just read the code. Chances are that if documentation exists, it’s no longer up to date.

                • auchschonda@feddit.de
                  link
                  fedilink
                  arrow-up
                  2
                  ·
                  1 year ago

                  Modularity. Part of it is defining a proper Interface for using the hidden complexity.

                  Exceptions are only one example. Functions can have behavior, inner states, prior calling requirements etc… you cannot read from its mere prototype.

                  Do you really want everyone to read the inner code to learn that?

                  Chances are that if documentation exists, it’s no longer up to date.

                  This risk also applies to descriptive function names. They can be poor, wrong or outdated, too.

    • wols@lemm.ee
      link
      fedilink
      arrow-up
      2
      ·
      1 year ago

      This works as a general guideline, but sometimes you aren't able to write the code in a way that truly self-documents.
      If you come back to a function after a month and need half an hour to understand it, you should probably add some comments explaining what was done and why it was done that way (in addition to considering if you should perhaps rewrite it entirely).
      If your code is going to be used by third parties, you almost always need more documentation than the raw code.

      Yes documentation can become obsolete. So constrain its use to cases where it actually adds clarity and commit to keeping it up to date with the evolving code.

  • joneskind@beehaw.org
    link
    fedilink
    arrow-up
    11
    ·
    1 year ago

    Of course we forget how it works.

    The whole point of the documentation is to help remembering.

  • xantoxis@lemmy.world
    link
    fedilink
    arrow-up
    10
    ·
    1 year ago

    An awful lot of people in here talking about automatic comment removal and I … don't believe it. I think a lot of you are making up stories. Show me proof that a build script removed your comments, because it's not just bad policy, it's literally insane. Nobody would do that. Anyone that thought of doing that would spot the folly of doing it within 5 minutes, and immediately stop. GTFO

  • Auzy@beehaw.org
    link
    fedilink
    arrow-up
    7
    ·
    edit-2
    1 year ago

    Let copilot do it. Junior developers can now efficiently write useless comments like the rest of us

    • Inktvip@lemm.ee
      link
      fedilink
      arrow-up
      4
      ·
      1 year ago

      I'm very much a novice coder, but I often find myself doing the opposite. Write a good comment and let copilot write the actual code.

      • NathanM@sopuli.xyz
        link
        fedilink
        arrow-up
        10
        ·
        1 year ago

        Yeah I wouldn't rely on that, especially early in your coding journey. The less external resources helping you the better, so you're encouraged to problem solve and figure out your own solutions, even if it takes longer.

        • Inktvip@lemm.ee
          link
          fedilink
          arrow-up
          1
          ·
          1 year ago

          I definitely rely on documentation more than copilot, since I've noticed that the code it writes is only ever as good as your own codebase.

          Most of the stuff I code is API wrappers to get arbitrary data into a format our broadcast graphics system can understand. Once all the data structures are properly defined copilot is extremely useful in populating all the API endpoints.

          The actual problem solving is getting the data in the first place and morphing it into the correct format.

  • SocialMediaRefugee@lemmy.ml
    link
    fedilink
    arrow-up
    4
    ·
    1 year ago

    Better yet. Only guy who knew the code retires/quits. The next guy who inherits the code finds out nothing was documented and it was all in the previous guy's head. Next guy has to spend weeks analyzing the code, asking coworkers who shake their heads and buying beers after work to get the previous guy to help him.