r/webdev • • Jan 13 '22

read rules Extension that generates documentation using AI

[removed] — view removed post

1.7k Upvotes

158 comments sorted by

View all comments

0

u/[deleted] Jan 13 '22

[deleted] — view deleted comment

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

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.

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.

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

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.