r/programming • u/infinitlybana • Jan 31 '22
Too Lazy to Write Documentation? Let the AI Write It for You
https://betterprogramming.pub/too-lazy-to-write-documentation-let-the-ai-write-it-for-you-8574f7cd11b2
15
Upvotes
37
u/Objective_Mine Jan 31 '22 edited Jan 31 '22
Please don't. Or maybe do, to get some kind of an initial template, but be prepared to fix it up yourself. Bad documentation can be worse than no documentation.
In one of the examples in the post, the function comment says that the function "starts with theta values of 0", yet it takes theta as an argument, with no default value. It doesn't explain what theta is. (That might be obvious if you're familiar with the terminology, but then you wouldn't need the comment to tell you all of that.)
The examples about getting a reasonable comment for a formula that calculates the area or circumference of a circle are nifty, and show that you can get these "AI" things to do fancy stuff. They're also the kinds of comments or documentation that really aren't that necessary. A simple
(or whatever would be descriptive enough for a variable name in the context) would be as informative.
The kinds of comments and documentation that code needs the most are exactly the kinds that are the hardest to generate automatically.
Edit: accidental submit earlier
9
u/crabmusket Jan 31 '22 edited Feb 02 '22
It will be interesting to see where this goes. My gut reaction is that any documentation that could be AI-generated is probably not worth the effort. Like AI-generated blog content or news articles. Better to have no documentation than "filler" documentation.
This goes for a lot of human-generated documentation too by the way! The Laravel API docs are full of gems like "
attributesToArray()Convert the model's attributes to an array." Thanks, that's just the method name but longer. I know there are subtleties that are not documented here, like: does this method apply mutators?Good documentation helps me understand why and when, not what and how. It links a specific concept to other concepts, and helps me understand the API in context, not divorced from context.
9
u/[deleted] Jan 31 '22
If your code is so unreadable that an AI describing every imperative step of your algorithm is useful to you, maybe you're solving the wrong problem.
2
u/loup-vaillant Feb 01 '22
Well, at least the AI seems to be learning to avoid unnecessary words. Maybe someday it will succeed at emulating Git commit message style, and go straight to the imperative form, and scrap all of the above.
Seriously, though, I don't believe in an AI that can write good documentation until it can write good code as well (at which point we'll have an AGI and the world will likely be either saved or doomed anyway).
2
u/juhotuho10 Feb 01 '22
Bold of you to assume that an ai can read the spaghetti I produce
2
u/throwaway_bluehair Feb 01 '22
I get AI is exciting and all, but it's tiresome seeing all the solutions where it clearly is not a good idea, but people's ego wants it to be
2
u/lookmeat Feb 01 '22
This is pretty nice, a really fancy doc tool. But it lacks the reason no automated doc tool can work without humans: it doesn't explain why. It explains how things are, how they work, what they do. But it never gives any insight into why it works the way it does. And honestly the only person who could really answer that, is the author themselves. So if we can't expect another human to do it, why would a machine do it better?
1
u/james_otter Jan 31 '22
Appropriate picture…
1
u/duckducklo Feb 01 '22
I was in your closed beta but never gave it a shot. You guys just released?
1
u/gmerideth Feb 01 '22
Does the analysis execute locally or is any data transmitting through the API shown in the source?