The problem with complex code is usually branches / conditionality.
Also complex indexing or expressions.
This stuff very rapidly stops being expressible in narrative form because the details can't be "compressed".
The explanation starts to look like legalese and you realise the code itself is the more compact and legible expression.
Ideally an autocommenter will be able to take a hand matmult and write "compute the surface normal" (this is an example where apparently high local detail can map to good conceptual compression) but actually that is the best possible case.
When it comes to important but somewhat arbitrary stuff like shipping or tax rules, english will not speed comprehension and is less good than a tageted dsl or well thought out tables.
The core problem is that "sometimes there is no simple explanation".
That’s all fine and good but the code exists already and even if I think its domain is an exceptionally good candidate for a DSL I can’t snap my fingers and make it morph into what I wish it was. And I can’t get there gradually without understanding what it is.
I’m well acquainted with its complexity but I need to articulate it coherently to justify changing any of it, not just to myself but to my team and stake holders. I’m not looking for a simple explanation. I’m looking forward to having tools help me navigate a very complicated explanation.
I also don’t understand the motivation here or upthread to splain the problem I’m solving away as some nihilistic unsolvable thing when I’m saying I see real prospects of this helping me. I mean, you’re welcome to whatever nihilism you see fit in your course of action but I personally don’t benefit from being told things I find potentially useful are not useful for me, actually.
So a better "output" might be a kind of chatbot that will answer questions about that particular piece of code. Basically it understands every detail including branches and you can ask whether a specific assumption is correct.
I don't think we're there yet (because complicated side effects etc. are a thing) but I would rather have such a solution than some text to read, after all I'd be using such a tool for code I cannot comprehend just by reading it.
Also complex indexing or expressions.
This stuff very rapidly stops being expressible in narrative form because the details can't be "compressed".
The explanation starts to look like legalese and you realise the code itself is the more compact and legible expression.
Ideally an autocommenter will be able to take a hand matmult and write "compute the surface normal" (this is an example where apparently high local detail can map to good conceptual compression) but actually that is the best possible case.
When it comes to important but somewhat arbitrary stuff like shipping or tax rules, english will not speed comprehension and is less good than a tageted dsl or well thought out tables.
The core problem is that "sometimes there is no simple explanation".