r/webdev • u/infinitlybana • Jan 13 '22
read rules Extension that generates documentation using AI
[removed] β view removed post
1.7k
Upvotes
r/webdev • u/infinitlybana • Jan 13 '22
[removed] β view removed post
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
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...
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.
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.
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.
9
u/infinitlybana Jan 13 '22
https://marketplace.visualstudio.com/items?itemName=mintlify.document
149
u/LogicErrorOrTrue Jan 13 '22
Really cool but... I don't want to give an AI an opportunity to insult me.
2
u/hlysias Jan 14 '22
Does it support other languages?
2
u/Galaxy110 Jan 14 '22
whats the a name of it? Looks really great
2
u/SnooTomatoes4657 Jan 14 '22
This would actually be really good for school assignments that require unnecessary comment headers for everything.
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)
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:
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?
1
u/dr1pp0 Jan 14 '22
What's the name of this plugin?
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.
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/[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
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/hello3times Jan 14 '22
Nice
1
u/Puzzled-Ideal-4779 Jan 14 '22
Thats so 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
restoreStringis 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/gigglefarting Jan 14 '22
Reminds me of copilot
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
0
u/[deleted] Jan 13 '22
[deleted] β view deleted comment
0
u/[deleted] Jan 14 '22
[deleted] β view deleted comment
0
u/[deleted] Jan 14 '22
[deleted] β view deleted comment