To clarify my snarky “junior developer” comment about code documentation in yesterday’s post about the JetBrains AI plugin, good documentation describes the intent of the code, it isn’t a blow-by-blow description of what the code does. While the ideal of literate programming is not practical for most software, it remains somewhat of a north star – you want to document what is not in the code, the rationale. So many beginners in this profession miss that point.
This is where the AI plugin has a hard time. It can only infer intent from the code as it is written. It doesn’t know what you had in your head while writing the code. It can’t tell whether this was a simple idea with a convoluted expression in code, for example. To be fair, it still is a starting point – sometimes, the required incremental description is small… Still, it falls far short of something good out of the box.
I fear that the automated descriptive documentation like this is only going to reinforce the misconception that “the code is the documentation” because this kind of documentation doesn’t add much beyond reading the code.n