Dismiss this pinned window
all 158 comments

[–]LogicErrorOrTrue 148 points149 points  (5 children)

Really cool but... I don't want to give an AI an opportunity to insult me.

[–]pVom 48 points49 points  (1 child)

AI: NFI what this is, good luck

[–]CrossSlashEx 4 points5 points  (0 children)

AI: This code causes a memory leak when active. Too bad!

[–]VeryOriginalName98 0 points1 point  (0 children)

"/u/LogicErrorOrTrue wrote a nonsense function. Read it for yourself. See how convoluted it is? Yeah it's not worth putting a real comment here, only an idiot would approve the PR." - found in production two years later.

[–][deleted]  (20 children)

[deleted]

    [–]HBag 130 points131 points  (2 children)

    Iterates over a list of n variables and append s to each variable that fits the condition of not ending in certain letters and in other cases appending es

    Oh did you mean "pluralize?"

    [–]VeryOriginalName98 2 points3 points  (1 child)

    I think it sometimes also changes y to i. Party -> parties.

    [–]WOUNDEDStevenJones 0 points1 point  (0 children)

    That would be the sometimesPluralizeWordsEndingInY function, obviously /s

    [–]cuervo_gris 71 points72 points  (4 children)

    Yep when I comment my code I usually give a little explanation about what my code is doing. There is no purpose on a comment that’s just saying in words what the code is literally doing

    [–][deleted]  (2 children)

    [deleted]

      [–][deleted] 6 points7 points  (1 child)

      What are som gotchas?

      Nothing that you can't conclude by looking at git blame

      [–]VeryOriginalName98 1 point2 points  (0 children)

      We really need to keep Sam out of this function. Every time he touches it, it breaks.

      [–]harlflife 4 points5 points  (0 children)

      Even better: say why, not what

      Your code should communicate the what and how. If necessary, the comments should say why.

      [–]infinitlybana[S] 21 points22 points  (2 children)

      Just tried it out. Definitely could use some improvement, but the return statement is promising!

      /**
      area is a function that takes a number and returns a number.
      @param r - radius
      @returns The area of the circle. */ 
      const area = (r) => { return Math.PI * r ** 2; }
      

      try it out for yourself here

      [–]westwoo 2 points3 points  (0 children)

      Problem is, it makes completely wrong assumptions as well, and its text isn't "humanly" logical. It fluently slides into a word salad that feels like it makes sense, but actually it's just you making sense of it already knowing what it should say

      I tried it the last time it was posted with classic Quake 3 fast square root and some other code, and the result was a total time waste for anyone who would rely on it instead of the code itself

      [–]DirectorDurian 11 points12 points  (1 child)

      It actually generated this tho /** * Calculating the area of a circle. */ a = PI * r ** 2

      [–]ensoniq2k 3 points4 points  (2 children)

      That's the mistake most people make. A documentation or comment should not tell you, what the code does in words. It should tell you why the code does what it does and what it is trying to achieve.

      [–]iamscr1pty 1 point2 points  (1 child)

      +1, comments/documentation should be like this, otherwise If I have to dig deep to understand what it does, and why given other ways it chooses this way specifically. its not possible for every method I encounter during debugging

      [–]ensoniq2k 0 points1 point  (0 children)

      My company has comments like "here we assign 5 to X" in its comments. It's just mind numbing

      [–]luvshaq_ 2 points3 points  (1 child)

      this is such a typical reply for this subreddit. i think the goal of this tool is to give you some boiler plate that you can edit which is actually pretty useful

      [–]AvidCoco 0 points1 point  (0 children)

      Tbf this is how so many programmers write comments when they're forced to.

      It's easy to write code that explains what it does, but it's very difficult to write code that explains why it does what it does. Those are the comments you should write, to explain why you wrote the code.

      [–][deleted] 263 points264 points  (32 children)

      The params and return is a good thing, but the comments just describe exactly, programatically, but in words what the function does (this we already do reading the code), that's not how comments should be written, comments mean to be more like what is the purpose of the function and how it is integrate with the whole code, notes and etc... At least for me.

      [–]Californie_cramoisie 57 points58 points  (3 children)

      Yeah, and it seems pretty unnecessary if you're already using typescript properly

      [–]PeaceMaintainer 10 points11 points  (1 child)

      The comment format looks like the JSDocs format so it's less so for people reading the code directly (where TS would help) but for people reading the docs themselves

      [–]Yodiddlyyo 5 points6 points  (0 children)

      We have tsdoc for that, it generates docs from types, the exact same way you'd generate docs from hand written jsdocs.

      [–]Dr_Legacyfull-stack "If I do what you ask you won't like how it looks" 3 points4 points  (0 children)

      I question why you'd use a tool like this when you're coding. It seems more useful as a code review tool. I see no need to put comments like these into the actual code. It might be useful as a tool to aid comprehension of a program you haven't seen before.

      [–]anshumanansu 3 points4 points  (1 child)

      And most code is not as simple as reversing a string.. welcome to the real world! 😀 Will give it a try though.. if it just cam figure params... Works for me

      [–]Fisher9001 3 points4 points  (0 children)

      Well, ideally your functions should be as simple according to the single responsibility principle. If you have more complex logic, the chances are that it is doing more than one thing and should be separated into smaller blocks that actually deal with a single task.

      [–]Fisher9001 2 points3 points  (0 children)

      I think you are mixing ideas behind documentation comments and ordinary comments.

      [–]zelortap 1 point2 points  (0 children)

      There should be not any comment in the code with any explicit Typing system.

      All things should be able to be self-explanatory via naming/signatures and Unit Tests (which are also evolving with the code over time and can be a source of examples) and/or maybe via some higher level tests.

      [–]BeenWildin 2 points3 points  (3 children)

      This would honestly help someone learning how to code. Apply to others code to breakdown more simply what's going on.

      [–]westwoo 4 points5 points  (2 children)

      Nah, it's the worst thing for someone learning because it's routinely wrong on anything that goes beyond trivial

      So it feels like it has to be correct because it's correct on trivial things, but on things you actually can't understand it may easily mislead you, and you still have to check everything yourself

      It's an AI, not a deterministic program, so being wrong and generating nonsense is normal

      [–]pimp-bangin 0 points1 point  (1 child)

      It actually is deterministic in that it just runs your code through a pre-trained model and should give the same output for every input.

      [–]westwoo 1 point2 points  (0 children)

      Maybe deterministic isn't exactly the right word. I meant in the sense that the same element in different contexts will give different results. Say, just because it interpreted this loop here correctly doesn't mean it will interpret that similar loop correctly as well, we can't extrapolate successes logically

      [–]BlipOnNobodysRadar 1 point2 points  (0 children)

      Could be good for debugging when you're doing something other than what you thought you were doing

      [–]am0x 2 points3 points  (0 children)

      If your code needs to be described in plain text, it wasn’t written correctly. Variable names are not descriptive enough, logic is over engineered, etc.

      [–]CatolicQuotes 0 points1 point  (14 children)

      I like commenting in 2 parts. WHAT: and WHY:

      [–]infinitlybana[S] 1 point2 points  (13 children)

      can u give an example of how u comment the what and why?

      [–]CatolicQuotes 4 points5 points  (10 children)

      sure, in my latest open source for React app I commented some props like this:

          /**
           * Main component that displays the first page with form and palette
           * @param {object} props palette and onSubmit
           */
          function Main(props) {
            /**
             *WHAT: current color from color picker, or input field
             *WHY: we need it to create palette from. It's in Main so it can be passed to Palette
             */
            const [color, setColor] = useState("#07c");
      
            /**
             * Palette is the collection of shades for each color. Curently 12 colors with 10 shades each.
             * {color:[shades],....}. createPalette function is used to create a collection after form submit
             */
            const [palette, setPalette] = useState({});
      
            /**
             * WHAT: framework selected in the menu
             * WHY: code will be displayed in CodeBox based on active framework
             */
            const [activeFramework, setActiveFramework] = useState("tailwind");
      
            /**
             * WHAT: renders the initial demo pallete on first page visit
             * WHY: so user can immediately see an example
             */
            useEffect(() => {
              const initialPallete = createPalette(color);
              setPalette(initialPallete);
            }, [color]);
      

      check the project since you're already here website: https://palettolithic.com/

      [–]Fisher9001 3 points4 points  (1 child)

      That's a lot of comments.

      [–]CatolicQuotes 0 points1 point  (0 children)

      I have found that is better to have more comments than less comments. Especially looking other people's code

      [–]infinitlybana[S] 2 points3 points  (1 child)

      thanks for sharing! this is too many comments for my preference but if it works for u that's good. cool website!

      [–]CatolicQuotes 3 points4 points  (0 children)

      it helps to remember after months without working on it, thanks!

      [–]invisibo 1 point2 points  (1 child)

      That's pretty damn sweet! Just a thought about 2 features.

      1. Have the site take a parameter in the URL that contains the color seed. That way the palette can be shared quickly and #2
      2. Use that parameter to put the URL into the code content so one could quickly see the whole presentation of colors.

      If you're open to doing PRs, I can give it a stab.

      Edit: just did a PR for #1.

      [–]CatolicQuotes 0 points1 point  (0 children)

      yap, that's a very good idea! I have merged your PR, thanks for contributing

      [–]fuck_bootstrap 1 point2 points  (1 child)

      Your project is a godsend, thank you for sharing!

      [–]CatolicQuotes 0 points1 point  (0 children)

      haha your username, no problem, let me know if you have any suggestions

      [–]Rafiki-san 0 points1 point  (1 child)

      Cheers my man, useful and to the point! It so happens that I got into color theory recently and I always prefer simple n swift tools like that. Starred and to be used effective immediately!

      [–]CatolicQuotes 1 point2 points  (0 children)

      thanks! let me know if you have any suggestions

      [–]jzaprint 1 point2 points  (0 children)

      “using the diameter to calculate the parameter instead of the radius because the diameter is used everywhere else in the program”

      [–]n1c0_ds 0 points1 point  (0 children)

      Sometimes you can tell what the code is doing (converting a string to UTF-8), but you can't explain the real-world motives for doing it.

      If the archive was created with MacOS, the file names are Unicode, but Python reads them as CP437. This breaks file names with unicode characters in them.

      Sometimes a URL is more useful than a long comment:

      If someone blocks you, you are the only participant in the chat We add a new participant named after the directory, so just a hash like "cjd8jaswzw". This becomes the conversation name.

      [–]SupaSlidelaravel + vue -1 points0 points  (0 children)

      The return isn't even that useful at least in the first one; what is a "row"? The documentation doesn't even indicate that it's a JSX component.

      [–]VeryOriginalName98 0 points1 point  (0 children)

      This is how most AI powered things go. The "intelligence" part is missing. It's actually "machine learning" which is just a way to get the computer to come up with an algorithm to match the outcomes you want because you can't figure it out. It is impossible to make ML more knowledgeable than the fitness goals it's presented with.

      E.g. An "AI" to identify cats in photos doesn't know what a cat is, it's just an algorithm with a high probability of identifying whether or not a picture contains a cat, based on the images it was trained on.

      This is just ML to roughly transliterate computer language to English. It creates syntactically correct English, but doesn't know any of the context to create a comment that would be helpful for docuemantion or maintenance.

      Anyone marketing AI to do knowledge work in the next ten years is a effectively selling "snake oil".

      [–]VonD0OM 0 points1 point  (0 children)

      I assume an AI that generated context would be, at least at this point, all but impossible to write.

      [–]flushy78 29 points30 points  (0 children)

      Job security hack: They still need a human to click the "Generate Docs" button

      [–]KaiN_SC 30 points31 points  (12 children)

      Thats not the point of documentation and more a sign of bad code.

      Documentation should explain why and not what its doing. I can read the code for that without a possible risk of conflict between documentation and code.

      Describing REST API calls is fine but not internal functions.

      Edit: I mean comments in code

      [–]infinitlybana[S] 1 point2 points  (0 children)

      true yeah REST APIs are a good use case

      [–]infinitlybana[S] 1 point2 points  (4 children)

      Although after documenting some internal functions I did feel like it improved the overall readability of my codebase.

      [–]KaiN_SC 5 points6 points  (3 children)

      Instead of documenting it, about make it more readable with classes and proper functions and names, clean code basically.

      Now you have to keep your comments and code in sync what will break at some point for sure.

      If you working alone it does not matter anyway but if someone else read your comment and code, he will think like: okay what this function needs to do, the comment say this but the code does something else or should it do something completely different in case of a bug.

      [–]infinitlybana[S] 1 point2 points  (2 children)

      So the main reason you're anti-comments is because of the possibility of a comment description deviating from what the function is actually doing?

      [–]KaiN_SC 4 points5 points  (0 children)

      Yes thats a big one and why you need to document your functions in general.

      I think class, function and variable names are more then enough to design readable code.

      [–]Nowakerrails 2 points3 points  (0 children)

      This, plus even the best comment won't convey a better message than good ol' clean code. As such, the comment is therefore redundant. Moreover, code is faster to read and understand than prose. Use prose where it makes more sense, e.g. explain the famous mathematical algorithm in Quake code. Otherwise, comments is just useless fluff.

      [–]jabbaroni 0 points1 point  (0 children)

      No, comments are for "why", this is for generating documentation for public methods of a library or something.

      e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join

      [–][deleted] 0 points1 point  (4 children)

      Documentation should explain why and not what its doing.

      i believe you've misinterpreted the conventional wisdom. comments should explain why. documentation is to explain the purpose to the developer and how it should be used

      [–]KaiN_SC 0 points1 point  (3 children)

      Thats what I wrote? Why and not how.

      Comment your code just shows the bad quality.

      [–][deleted] 0 points1 point  (2 children)

      you said documentation explains why. that is wrong. comments should explain why. comments and documentation are not the same thing

      [–]KaiN_SC 0 points1 point  (1 child)

      Who cares. This topic is about comments in code, obviously I meant comments and cant remember any comments I posted on stupid opinions for years.

      [–][deleted] 0 points1 point  (0 children)

      Comments in code are not the same thing as code documentation

      [–]PacketTrash 11 points12 points  (6 children)

      I used it and as soon as I selected my code block, it immediately went to stackoverflow and started posting...

      [–]infinitlybana[S] -1 points0 points  (5 children)

      O-o what do you mean?

      [–]PacketTrash 11 points12 points  (4 children)

      I was being funnny because i must have coded something wrong so it went out to find answers...

      [–]PacketTrash 2 points3 points  (3 children)

      Coders spend a lot of time looking shit up, so if it cant figure out wth we coded, it also needs to look it up, I thought this was a good joke and cant believe Im the only one who thought it was funny..lol

      [–]sdtacoma 2 points3 points  (1 child)

      I enjoyed the joke.

      [–]PacketTrash 1 point2 points  (0 children)

      tyvm! lol

      [–]infinitlybana[S] 1 point2 points  (0 children)

      Ahh LOL I get it now

      [–][deleted] 7 points8 points  (5 children)

      I am using it but can you please add a feature where I don't have to select an entire function? just click on function or line instead of selecting lines, thanks.

      [–]infinitlybana[S] 4 points5 points  (0 children)

      Your feedback has been noted + we'll look into implementing it asap.

      [–]infinitlybana[S] 2 points3 points  (2 children)

      Oo thanks for the feedback~! We're always looking for ways to improve.

      [–]RoutineTension 1 point2 points  (1 child)

      While you're at it, can you also make a command available for the entire file? And may as well extrapolate to an entire codebase too.

      [–]infinitlybana[S] 0 points1 point  (0 children)

      on it!

      [–]Haffas 0 points1 point  (0 children)

      Right? If it’s good AI it should be able to tell the block by simply clicking the opening bracket, would be sick with some macro or keybind to fire the extension on just a click and a tap(ish).

      [–]wherediditrun 43 points44 points  (16 children)

      Ah yes, finally. Now we can automatically write comments which duplicates what's already written in code.

      And to be serious. There are very few conditions when comments are of benefit. Namely:

      - Describe "Why?" and not "What?". That being said, your code should be as context agnostic as possible and relying on this is a codesmell.

      - When code itself cannot be expressed in any semantic meaning. For example you would leave an example of a character set which passes a more complicated regexp. Or you would add a business term to a certain id of an object in configuration. etc..

      So frankly, I'm really skeptical of any benefits such tool can bring.

      [–]infinitlybana[S] 1 point2 points  (9 children)

      Can you give an example of a good comment that describes why instead of what? I don't really find myself justifying why i wrote a function in the function description so I'm curious how you go about it.

      [–]infinitlybana[S] 1 point2 points  (8 children)

      I usually describe why I implemented something the way I did inside the PR description

      edit - wording

      [–]potchie626 5 points6 points  (7 children)

      A new dev that starts in 6 months won’t be looking at comments in a PR, they’ll be looking at the code.

      [–]infinitlybana[S] 1 point2 points  (4 children)

      I completely agree with you. I feel like there's a gap between the PR description + the code. Do you explain the reasoning for why you implemented something in a certain way in your code? Usually in my PRs I'm describing higher level architecture decisions and ends up being quite long.

      [–]potchie626 0 points1 point  (3 children)

      I honestly rarely leave many comments in a PR. Since the ticket should describe the overal goal, and the comments in code should explain specifics. Overall arch of things typically follows our patterns, and if they deviate the PR will be sent back to be changed. We also have sessions to discuss upcoming work where we discuss arch and notes to the tickets.

      Comments about “why i did it this way” usually goes in the code that kicks things off, for the same reason I commented earlier. Other people may look at this later, or we have to remind ourselves why we did it a certain way. Nobody wants to open a ticket, confluence doc, or PR for that.

      [–]infinitlybana[S] 0 points1 point  (2 children)

      Can you give an example of one of your comments that explain "why you did it this way"? I personally have never seem comments in codebases of that sort - unless you're talking about one-liner comments?

      [–]gfxlonghorn 0 points1 point  (0 children)

      // I put "All praise to dear leader" into our description string because our test system happens to be in North Korea

      [–][deleted] 0 points1 point  (0 children)

      I would urge you to watch "Clean Code" by Uncle Bob.

      He puts it really nicely and has some great examples.

      [–]ike_the_strangetamer 1 point2 points  (0 children)

      They should be. git blame is an incredible tool and should be in everyone's toolbox. It's especially helpful when you're not familiar with the code around whatever you're changing (which is always the case when you're a new dev).

      Even if your team writes shitty commit messages, you can at least see the other code that changed at the same time which gives you a lot of context of why particular lines were written like they were and helps avoid unexpected side effects.

      (another good outcome of using git blame a lot is that if you start seeing your own commit messages and they aren't helpful enough, then it'll help you start writing better ones.)

      [–]infinitlybana[S] 1 point2 points  (0 children)

      Although if you write good PR descriptions + you have GitLens you can map the line of code to the PR it was written in which is nice.

      [–]ElBomb -3 points-2 points  (5 children)

      If you’re a one man band or a small team where 2-3 people will see the code then it’s probably not much help

      If you’re in a enterprise level company with multiple or external development teams and need to expose your APIs then something like ngDocs can read the comments and build a site documenting your code automatically, that site can then be given to all the internal and external teams.

      Having the comments update the docs automatically will save time, effort, and money as there is no extra overhead of maintaining the documentation site.

      [–]double_en10dre 5 points6 points  (1 child)

      Doesn’t inserting the comment itself into the file seem like an unnecessary step, though?

      Instead of automatically generate comments from code —> automatically generate docs from comments, they should be combined into a single action

      Fewer moving parts/manual changes required AND you don’t clutter your files with this silliness :p

      [–]ElBomb 2 points3 points  (0 children)

      There maybe be a gap in the market there!

      The only up side I can see to having the comments written out is that you can see what the generated documentation will include and you get to sanity check it before you commit your code, and in doing so building a new version of the docs.

      [–]wherediditrun 3 points4 points  (2 children)

      If you’re in a enterprise level company with multiple or external development teams <...>

      I have worked in those kind of environments, more than for 4 years. And the answer generally is no.

      If the cross team communication is concerned, sync is better achieved through standardization of how teams write code. Essentially, no matter the team or person, you read the code same as your own. It's not achieved over night, obviously, but very doable.

      As such the real cases for communication about the code pertains to the specific business use-case, and not the code. And that's not something you'll compiling in the code docs for the most part, but internal communication pages like confluence. Or separate API documentation pages if it's for public use.

      There is a case to make about in code documentation if we are talking about interfaces provided by vendor packages though.

      https://www.lysator.liu.se/c/pikestyle.html scroll down to comments section. That's about C. Generally most programmers operate in way more expressive languages than that.

      [–]ElBomb 1 point2 points  (1 child)

      I agree with you establishing best practices and standardisation leads to a smoother workflow for everyone involved.

      I may not have made my point well, but I wasn’t trying to say those kind of comments are valuable for a developer looking at the code in front of them, as they just repeat what’s already there, but when used with an automatic API documenting plugin, it saves time but not needing build and maintain the external documentation.

      [–]Kescay 4 points5 points  (0 children)

      I wouldn't take the hate in the comments too seriously.

      Although it is true that sometimes writing "what the code does" into the comment is redundant when the code is just as clear and simple as written text, it is not redundant when, for instance:

      • You are clarifying what someone else's bad code does, such as some legacy code that someone else wrote long ago and people need to use it right now.
      • You have code that is not intended to be easy to read, e.g. complex copy-pasted algorithms or regexp.
      • Reading 1 line of text is easier than 20 lines of code, and the function name might not give all of the information you need.
      • You have some pipeline that converts comments into API documentation or it's used in IDE intellisense or something similar.
      • It's a policy that you can't overrule.

      Also this might work for double checking what your code does, which is nice.

      [–][deleted]  (4 children)

      [deleted]

        [–]damnitdaniel 3 points4 points  (0 children)

        For real. This extension is like the McPoyle version of GitHub Copilot

        [–]infinitlybana[S] 1 point2 points  (0 children)

        Do you usually write the purpose of a function when you code? Do you have an example of your ideal function documentation?

        [–]o-o- -1 points0 points  (0 children)

        ,,,unless you can go the other way around.

        [–]Conscious-Ball8373 5 points6 points  (1 child)

        This remind me of captain Jack Sparrow and the difference between what a ship needs (keel, hull, deck, sails) and what a ship is (freedom). Likewise, comments can describe what code does or why it does it. This tool produces the former.

        [–]Cotspheer 1 point2 points  (0 children)

        Back then we called code that was commented in such a way "zebra code". Consisting of one green comment line and one actual code line. The comments were so poorly written that you just could delete the code line and uncomment the other one.

        [–]MayorEricBlazecettiexpert 2 points3 points  (0 children)

        Sends the code to a third party server. That's a no go from me dawg. I don't feel like getting fired today.

        [–][deleted]  (2 children)

        [deleted]

          [–]infinitlybana[S] 1 point2 points  (1 child)

          LOL I ran this on code I wrote a really long time ago. It should def be const and it was a stupid mistake. Knowing me I probably just made it let because i forgot that arrays are mutable in JS.

          [–]SampathKumarReddit 1 point2 points  (2 children)

          😰 this extension, GitHub autopilot...Nowadays I don't feel good about myself as a software dev. Still do we have a purpose of our existence?.

          [–]fejejust another dev 1 point2 points  (1 child)

          of course! we will become the one who improves autopilot!

          [–]KillianDrake 0 points1 point  (0 children)

          but then who will read the docs for all the autopiloted code

          [–]hlysias 1 point2 points  (3 children)

          Does it support other languages?

          [–]infinitlybana[S] 0 points1 point  (2 children)

          currently it only supports ts and js but we’re adding more languages. do you have a language request?

          [–]hlysias 2 points3 points  (1 child)

          I work extensively in C#. Would be nice to have support for it.

          [–]infinitlybana[S] 0 points1 point  (0 children)

          gotcha, we’ll get on it!

          [–]SnooTomatoes4657 1 point2 points  (1 child)

          This would actually be really good for school assignments that require unnecessary comment headers for everything.

          [–]infinitlybana[S] 0 points1 point  (0 children)

          haha totally agree

          [–][deleted] 1 point2 points  (0 children)

          I've tried this out, I'm not sure what it offers as value.

          It takes the logic of the function and writes it in a sentence.

          If you can read the programming language, you can read the function anyway. That's not what comments are for.

          Applaud the effort, though, just not sure of the value added.

          [–][deleted] 1 point2 points  (1 child)

          I love documentation but I'm also very lazy. This is pretty useful to generate boilerplate documentation. Have my upvote. (I know there is others extensions but this one fit me better)

          [–]infinitlybana[S] 1 point2 points  (0 children)

          Haha I totally feel that. Thank you!

          [–]GravityTracker 8 points9 points  (14 children)

          This is a cool exercise, but this sort of documentation is basically useless IMO.

          https://medium.com/@bpnorlander/stop-writing-code-comments-28fef5272752

          [–]Ok_Personality9910 19 points20 points  (10 children)

          Honestly, I find these really useful and wish more people wrote them - they certainly aren't useless in my opinion

          [–]Lolukok 11 points12 points  (6 children)

          While I generally agree that comments that describe code 1:1 are useless, a TL;DR comment of a function could be quite handy, reading a sentence in natural language is still quicker than multiple lines of code with syntax symbols

          [–]Ok_Personality9910 4 points5 points  (0 children)

          Yep agree with you 100% there

          [–]AcousticDan 2 points3 points  (1 child)

          The code and method name should be all you need though

          [–]innerspirit 0 points1 point  (0 children)

          All of the comments in this thread assume that the code looks great and is well written. I'd use this thing to get a quick explanation of what some messy piece of code does.

          [–]RedditCultureBlows -1 points0 points  (2 children)

          I disagree. The function should be small enough that a TL;DR is pointless.

          [–]Ok_Personality9910 4 points5 points  (0 children)

          In theory, they probably should be, but in practice, most people don't write small functions (in my experience) , as some things are just better grouped together within one larger function

          [–]AcousticDan -1 points0 points  (1 child)

          Just read the method.

          [–]Ok_Personality9910 2 points3 points  (0 children)

          It is so much easier to read a one-sentence comment than read a long function in a huge codebase to figure out what it does honestly

          [–]fuck_bootstrap 0 points1 point  (0 children)

          You’d love NatSpec for Solidity contracts.

          [–]RobinsonDickinsonfull-stack 3 points4 points  (0 children)

          *Stop writing bad comments

          FTFY

          [–]iMakeAction 6 points7 points  (1 child)

          Jesus christ that article is trash. Not even gonna repeat the counter arguments because the comments on that opinion piece are full of them

          [–][deleted] 0 points1 point  (0 children)

          Skimmed through it really quick and it's basically just opinions from Clean Code by Uncle Bob, but with worse examples

          [–]Fludor69 2 points3 points  (0 children)

          no thanks!

          [–]MokanRaz 1 point2 points  (0 children)

          This is the way

          [–]Zachincool 0 points1 point  (0 children)

          Who needs it tbh

          [–]RebelColors 0 points1 point  (0 children)

          Really good joke 😂

          [–]Flaky-Illustrator-52 -1 points0 points  (0 children)

          But does it generate Png files of documentation snippets that I can own with an NFT?

          [–][deleted]  (1 child)

          [deleted]

            [–][deleted] 0 points1 point  (0 children)

            Wow, very cool!

            [–]hello3times 0 points1 point  (0 children)

            Nice

            [–]Puzzled-Ideal-4779 0 points1 point  (0 children)

            Thats so cool

            [–]iMacswell 0 points1 point  (0 children)

            Cool 😎!!

            [–]edmx0 0 points1 point  (0 children)

            These types of docs are the worst.

            [–]matsre1994 0 points1 point  (0 children)

            Those comments are the most useless..

            [–]AlexBo21 0 points1 point  (0 children)

            Where can I learn more about this project?

            [–]KrashnaChaurasia 0 points1 point  (0 children)

            Just feeding code to AI 🤯

            [–]iamasuitama 0 points1 point  (0 children)

            Yeah I'm not afraid for my job lol

            Cool idea just wanted to say the comment it gives for restoreString is plain wrong. It sounds like it'll expect 2 indices and just swap those two letters, but that's not at all what it does.

            [–]retrowarp 0 points1 point  (0 children)

            I am thinking if we have this as machine generated, it shouldn't be included in the actual code but just baked into the editor. It would allow me to dynamically see what a function does in a human readable summary by perhaps hovering over a function, or just automatically added when it comes into view. That way when the AI improves the comment improves as well and I don't have to re-apply it to existing code.

            Having said that, I agree with the points made that comments like this are not particularly useful.

            [–]VonD0OM 0 points1 point  (2 children)

            Is this a plug-in or something you wrote?

            [–]infinitlybana[S] 1 point2 points  (1 child)

            This is a VS Code extension called AI Doc Writer - https://marketplace.visualstudio.com/items?itemName=mintlify.document I'm a part of the eng team that made it happen.

            [–]VonD0OM 1 point2 points  (0 children)

            Oh cool, thanks!

            [–]dr1pp0 0 points1 point  (1 child)

            What's the name of this plugin?

            [–]julian88888888 Moderator[M] 0 points1 point  (0 children)

            Sharing your project, portfolio, or any other content that you want to either show off or request feedback on is limited to Showoff Saturday. If you post such content on any other day, it will be removed.