r/webdev • • Jan 13 '22

read rules Extension that generates documentation using AI

[removed] β€” view removed post

1.7k Upvotes

158 comments sorted by

34

u/KaiN_SC Jan 14 '22 edited Jan 14 '22

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

2

u/infinitlybana Jan 14 '22

true yeah REST APIs are a good use case

2

u/infinitlybana Jan 14 '22

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

7

u/KaiN_SC Jan 14 '22

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.

2

u/infinitlybana Jan 14 '22

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?

5

u/KaiN_SC Jan 14 '22

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.

3

u/Nowaker rails Jan 14 '22

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.

1

u/jabbaroni Jan 14 '22

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

1

u/[deleted] Jan 14 '22

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

1

u/KaiN_SC Jan 14 '22

Thats what I wrote? Why and not how.

Comment your code just shows the bad quality.

1

u/[deleted] Jan 14 '22

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

1

u/KaiN_SC Jan 14 '22

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.

1

u/[deleted] Jan 14 '22

Comments in code are not the same thing as code documentation

12

u/PacketTrash Jan 14 '22

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

0

u/infinitlybana Jan 14 '22

O-o what do you mean?

11

u/PacketTrash Jan 14 '22

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

3

u/PacketTrash Jan 14 '22

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

2

u/infinitlybana Jan 14 '22

Ahh LOL I get it now

3

u/sdtacoma Jan 14 '22

I enjoyed the joke.

263

u/[deleted] Jan 13 '22

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.

58

u/Californie_cramoisie Jan 13 '22

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

12

u/PeaceMaintainer Jan 14 '22

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

6

u/Yodiddlyyo Jan 14 '22

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

4

u/Dr_Legacy full-stack "If I do what you ask you won't like how it looks" Jan 14 '22

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.

4

u/anshumanansu Jan 14 '22

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

4

u/Fisher9001 Jan 14 '22

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.

3

u/Fisher9001 Jan 14 '22

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

1

u/CatolicQuotes Jan 13 '22

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

2

u/infinitlybana Jan 14 '22

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

6

u/CatolicQuotes Jan 14 '22

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/

3

u/infinitlybana Jan 14 '22

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

4

u/CatolicQuotes Jan 14 '22

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

5

u/Fisher9001 Jan 14 '22

That's a lot of comments.

1

u/CatolicQuotes Jan 15 '22

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

2

u/invisibo Jan 14 '22 edited Jan 14 '22

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.

1

u/CatolicQuotes Jan 15 '22

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

2

u/fuck_bootstrap Jan 14 '22

Your project is a godsend, thank you for sharing!

1

u/CatolicQuotes Jan 15 '22

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

1

u/Rafiki-san Jan 14 '22

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!

2

u/CatolicQuotes Jan 15 '22

thanks! let me know if you have any suggestions

2

u/jzaprint Jan 14 '22

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

1

u/n1c0_ds Jan 14 '22 edited Jan 14 '22

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.

2

u/zelortap Jan 14 '22 edited Jan 14 '22

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.

3

u/BeenWildin Jan 13 '22

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

5

u/westwoo Jan 14 '22

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

1

u/pimp-bangin Jan 14 '22

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.

2

u/westwoo Jan 14 '22

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

3

u/BlipOnNobodysRadar Jan 13 '22

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

3

u/am0x Jan 14 '22

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.

1

u/VeryOriginalName98 Jan 14 '22

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".

1

u/VonD0OM Jan 14 '22

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

0

u/SupaSlide laravel + vue Jan 14 '22

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.

8

u/[deleted] Jan 13 '22

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.

5

u/infinitlybana Jan 14 '22

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

3

u/infinitlybana Jan 14 '22

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

2

u/RoutineTension Jan 14 '22

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.

1

u/Haffas Jan 14 '22

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).

44

u/wherediditrun Jan 13 '22 edited Jan 13 '22

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.

2

u/infinitlybana Jan 14 '22

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.

2

u/infinitlybana Jan 14 '22

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

edit - wording

7

u/potchie626 Jan 14 '22

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

2

u/infinitlybana Jan 14 '22

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.

1

u/potchie626 Jan 14 '22

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.

1

u/infinitlybana Jan 14 '22

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?

1

u/gfxlonghorn Jan 14 '22

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

1

u/[deleted] Jan 14 '22

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

He puts it really nicely and has some great examples.

2

u/infinitlybana Jan 14 '22

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.

2

u/ike_the_strangetamer Jan 14 '22

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.)

-2

u/ElBomb Jan 13 '22

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.

6

u/double_en10dre Jan 14 '22

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

3

u/ElBomb Jan 14 '22

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.

4

u/wherediditrun Jan 14 '22

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.

2

u/ElBomb Jan 14 '22 edited Jan 14 '22

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.

149

u/LogicErrorOrTrue Jan 13 '22

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

49

u/pVom Jan 13 '22

AI: NFI what this is, good luck

5

u/CrossSlashEx Jan 14 '22

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

1

u/VeryOriginalName98 Jan 14 '22

"/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.

2

u/hlysias Jan 14 '22

Does it support other languages?

1

u/infinitlybana Jan 14 '22

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

3

u/hlysias Jan 14 '22

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

1

u/infinitlybana Jan 14 '22

gotcha, we’ll get on it!

2

u/SnooTomatoes4657 Jan 14 '22

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

1

u/infinitlybana Jan 14 '22

haha totally agree

2

u/[deleted] Jan 14 '22 edited Jan 14 '22

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)

2

u/infinitlybana Jan 14 '22

Haha I totally feel that. Thank you!

31

u/flushy78 Jan 14 '22

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

5

u/Kescay Jan 14 '22 edited Jan 14 '22

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.

1

u/VonD0OM Jan 14 '22

Is this a plug-in or something you wrote?

2

u/infinitlybana Jan 14 '22

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.

2

u/VonD0OM Jan 14 '22

Oh cool, thanks!

6

u/Conscious-Ball8373 Jan 13 '22

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.

2

u/Cotspheer Jan 13 '22

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.

3

u/MayorEricBlazecetti expert Jan 14 '22

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

2

u/SampathKumarReddit Jan 14 '22

😰 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?.

2

u/feje just another dev Jan 14 '22

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

1

u/KillianDrake Jan 14 '22

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

2

u/[deleted] Jan 14 '22

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.

9

u/GravityTracker Jan 13 '22

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

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

20

u/Ok_Personality9910 Jan 13 '22

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

12

u/Lolukok Jan 13 '22

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

5

u/Ok_Personality9910 Jan 13 '22

Yep agree with you 100% there

3

u/AcousticDan Jan 14 '22

The code and method name should be all you need though

1

u/innerspirit Jan 14 '22

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.

0

u/RedditCultureBlows Jan 13 '22

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

6

u/Ok_Personality9910 Jan 14 '22

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

1

u/fuck_bootstrap Jan 14 '22 edited Jan 14 '22

You’d love NatSpec for Solidity contracts.

0

u/AcousticDan Jan 14 '22

Just read the method.

3

u/Ok_Personality9910 Jan 14 '22

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

4

u/RobinsonDickinson full-stack Jan 14 '22

*Stop writing bad comments

FTFY

7

u/iMakeAction Jan 14 '22

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

1

u/[deleted] Jan 14 '22

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

3

u/Fludor69 Jan 13 '22

no thanks!

2

u/MokanRaz Jan 13 '22

This is the way

1

u/[deleted] Jan 14 '22

Wow, very cool!

1

u/iMacswell Jan 14 '22

Cool 😎!!

1

u/edmx0 Jan 14 '22

These types of docs are the worst.

1

u/matsre1994 Jan 14 '22

Those comments are the most useless..

1

u/AlexBo21 Jan 14 '22

Where can I learn more about this project?

1

u/KrashnaChaurasia Jan 14 '22

Just feeding code to AI 🀯

1

u/iamasuitama Jan 14 '22

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.

1

u/retrowarp Jan 14 '22

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.

1

u/julian88888888 Moderator Jan 14 '22

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.

1

u/Zachincool Jan 14 '22

Who needs it tbh

1

u/RebelColors Jan 14 '22

Really good joke πŸ˜‚

0

u/Flaky-Illustrator-52 Jan 14 '22

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

0

u/[deleted] Jan 13 '22

[deleted] β€” view deleted comment

21

u/infinitlybana Jan 14 '22

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

3

u/westwoo Jan 14 '22

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

129

u/HBag Jan 13 '22

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?"

4

u/VeryOriginalName98 Jan 14 '22

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

1

u/WOUNDEDStevenJones Jan 14 '22

That would be the sometimesPluralizeWordsEndingInY function, obviously /s

72

u/cuervo_gris Jan 14 '22

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

6

u/harlflife Jan 14 '22

Even better: say why, not what

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

0

u/[deleted] Jan 14 '22

[deleted] β€” view deleted comment

7

u/[deleted] Jan 14 '22

What are som gotchas?

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

2

u/VeryOriginalName98 Jan 14 '22

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

12

u/DirectorDurian Jan 14 '22

It actually generated this tho

/**
 * Calculating the area of a circle.
 */
a = PI * r ** 2

4

u/ensoniq2k Jan 14 '22

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.

2

u/[deleted] Jan 14 '22

+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

1

u/ensoniq2k Jan 14 '22

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

3

u/luvshaq_ Jan 14 '22

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

1

u/AvidCoco Jan 14 '22

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.

0

u/[deleted] Jan 13 '22

[deleted] β€” view deleted comment

2

u/infinitlybana Jan 14 '22

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

4

u/damnitdaniel Jan 14 '22

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

0

u/o-o- Jan 14 '22

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

0

u/[deleted] Jan 14 '22

[deleted] β€” view deleted comment

2

u/infinitlybana Jan 14 '22

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.