AI for doc comments by Mark Seemann
A solution in search of a problem?
I was recently listening to a podcast episode where the guest (among other things) enthused about how advances in large language models mean that you can now get these systems to write XML doc comments.
You know, these things:
/// <summary> /// Scorbles a dybliad. /// </summary> /// <param name="dybliad">The dybliad to scorble.</param> /// <param name="flag"> /// A flag that controls wether scorbling is done pre- or postvotraid. /// </param> /// <returns>The scorbled dybliad.</returns> public string Scorble(string dybliad, bool flag)
And it struck me how that's not the first time I've encountered that notion. Finally, you no longer need to write those tedious documentation comments in your code. Instead, you can get Github Copilot or ChatGPT to write them for you.
When was the last time you wrote such comments?
I'm sure that there are readers who wrote some just yesterday, but generally, I rarely encounter them in the wild.
As a rule, I only write them when my modelling skills fail me so badly that I need to apologise in code. Whenever I run into such a situation, I may as well take advantage of the format already in place for such things, but it's not taking up a big chunk of my time.
It's been a decade since I ran into a code base where doc comments were mandatory. When I had to write comments, I'd use GhostDoc, which used heuristics to produce 'documentation' on par with modern AI tools.
Whether you use GhostDoc, Github Copilot, or write the comments yourself, most of them tend to be equally inane and vacuous. Good design only amplifies this quality. The better names you use, and the more you leverage the type system to make illegal states unrepresentable, the less you need the kind of documentation furnished by doc comments.
I find it striking that more than one person wax poetic about AI's ability to produce doc comments.
Is that, ultimately, the only thing we'll entrust to large language models?
I know that that they can do more than that, but are we going to let them? Or is automatic doc comments a solution in search of a problem?
